cantabile_edge, cantabile_modbus, cantabile_eebus 0.1.400: full source

This commit is contained in:
Setti Solutions S.R.L committed 2026-10-30 08:26:45 +02:00
1 parent 343331d234
commit d5fbcacaa4
176 files changed
+32511 -19

No files matched your search

+114
View File
@@ -0,0 +1,114 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
// Data bundles for the agent (data only, never code that runs):
// tariffs (prices for the next 48 h), models (the forecasts' data), a
// building box's flats and the devices' protection (acl: it
// never expires; a newer one replaces it). Fleet
// sends one as a signed command, `tariff` or `model`, with args
// {"bundle": base64 of the bundle's JSON bytes, "sig": base64 of their
// signature with the BUNDLE key}. The command itself is checked with the
// command key (checkCommand); here the bundle's own signature, its kind, site
// and expiry, and that it is not older than the one the agent has. Then the
// JSON goes into the agent's state directory (tariff.json, model.json),
// which the agent re-reads when it changes.
import (
"crypto"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
"log/slog"
"os"
"os/exec"
"path/filepath"
"time"
)
// devicesPolicy: on a Hub, the devices tool writes the protection in force
// for add-ons once a new acl bundle is stored (its timer does it too).
var devicesPolicy = func() {
if out, err := exec.Command("/usr/lib/cantabile/devices", "policy").CombinedOutput(); err != nil {
slog.Warn("devices policy", "error", err, "output", string(out))
}
}
const bundleMax = 256 << 10 // a tariff is a few kB; a model's data well under this
// bundleCert: the bundle key's certificate (CANTABILE_BUNDLE_CERT). Read for
// each bundle: a box may get it after its link started.
func (l *link) bundleCert() (crypto.PublicKey, error) {
return commandKey(l.cfg.BundleCert)
}
// bundleHead: the fields every bundle has (v1).
type bundleHead struct {
V int `json:"v"`
Kind string `json:"kind"`
ID string `json:"id"`
Site string `json:"site"`
Issued int64 `json:"issued"`
Expires int64 `json:"expires"`
}
// checkBundle: the bundle's bytes and head, if signed with the bundle key,
// of this kind, for this site (a model may be for every site: "*"), not
// expired and not issued in the future.
func checkBundle(key crypto.PublicKey, kind, site string, args map[string]string, now time.Time) ([]byte, bundleHead, error) {
var h bundleHead
data, err1 := base64.StdEncoding.DecodeString(args["bundle"])
sig, err2 := base64.StdEncoding.DecodeString(args["sig"])
switch {
case err1 != nil || err2 != nil || len(data) == 0 || len(sig) == 0:
return nil, h, errors.New("bundle and sig: base64 needed")
case len(data) > bundleMax:
return nil, h, fmt.Errorf("bundle larger than %d bytes", bundleMax)
case !verify(key, data, sig):
return nil, h, errors.New("bad bundle signature")
}
if json.Unmarshal(data, &h) != nil || h.V != 1 {
return nil, h, errors.New("not a v1 bundle")
}
switch {
case h.Kind != kind:
return nil, h, fmt.Errorf("a %q bundle, not %q", h.Kind, kind)
case h.Site != site && !(kind == "model" && h.Site == "*"):
return nil, h, errors.New("not for this site")
case h.Expires != 0 && now.Unix() >= h.Expires:
return nil, h, errors.New("expired")
case h.Issued > now.Add(time.Hour).Unix():
return nil, h, errors.New("issued in the future")
}
return data, h, nil
}
// bundleCmd: a `tariff`, `model` or `flats` command (already checked as a
// command); flats: a building's own box gets its flats for Home Assistant.
func (l *link) bundleCmd(c command, now time.Time) (bool, string) {
key, err := l.bundleCert()
if err != nil {
return false, "no bundle certificate on this box: " + err.Error()
}
data, h, err := checkBundle(key, c.Cmd, l.id, c.Args, now)
if err != nil {
return false, c.Cmd + " refused: " + err.Error()
}
path := filepath.Join(l.cfg.AgentState, c.Cmd+".json")
var cur bundleHead
if b, err := os.ReadFile(path); err == nil && json.Unmarshal(b, &cur) == nil && cur.Issued > h.Issued {
return false, fmt.Sprintf("%s refused: older than the one the agent has (%s)", c.Cmd, cur.ID)
}
if err := os.MkdirAll(l.cfg.AgentState, 0o755); err != nil {
return false, err.Error()
}
tmp := path + ".tmp"
if err := os.WriteFile(tmp, data, 0o644); err != nil {
return false, err.Error()
}
if err := os.Rename(tmp, path); err != nil {
return false, err.Error()
}
return true, fmt.Sprintf("%s %s stored for the agent", c.Cmd, h.ID)
}
+149
View File
@@ -0,0 +1,149 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"crypto/ecdsa"
"crypto/elliptic"
"crypto/rand"
"crypto/sha256"
"crypto/x509"
"crypto/x509/pkix"
"encoding/base64"
"encoding/json"
"encoding/pem"
"math/big"
"os"
"path/filepath"
"strings"
"testing"
"time"
)
// bundleArgs: a bundle and its signature as fleet sends them.
func bundleArgs(t *testing.T, k *ecdsa.PrivateKey, b map[string]any) map[string]string {
data, _ := json.Marshal(b)
sum := sha256.Sum256(data)
sig, err := ecdsa.SignASN1(rand.Reader, k, sum[:])
if err != nil {
t.Fatal(err)
}
return map[string]string{"bundle": base64.StdEncoding.EncodeToString(data), "sig": base64.StdEncoding.EncodeToString(sig)}
}
func certFile(t *testing.T, k *ecdsa.PrivateKey) string {
tpl := &x509.Certificate{SerialNumber: big.NewInt(1), Subject: pkix.Name{CommonName: "bundles"},
NotBefore: time.Now().Add(-time.Hour), NotAfter: time.Now().Add(time.Hour)}
der, err := x509.CreateCertificate(rand.Reader, tpl, tpl, &k.PublicKey, k)
if err != nil {
t.Fatal(err)
}
p := filepath.Join(t.TempDir(), "bundles.pem")
os.WriteFile(p, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}), 0o644)
return p
}
func TestBundles(t *testing.T) {
k, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
other, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
site := strings.Repeat("ab", 16)
now := time.Now()
l := &link{id: site, cfg: config{BundleCert: certFile(t, k), AgentState: t.TempDir()}}
tariff := func(id string, issued int64) map[string]any {
return map[string]any{"v": 1, "kind": "tariff", "id": id, "site": site, "issued": issued,
"start": now.Unix(), "step_s": 900, "steps": 192, "expires": now.Add(48 * time.Hour).Unix(),
"currency": "EUR", "unit": "ct/kWh", "import": []float64{30}, "export": []float64{8}}
}
cmd := func(name string, args map[string]string) command { return command{ID: "c", Cmd: name, Args: args} }
if ok, msg := l.bundleCmd(cmd("tariff", bundleArgs(t, k, tariff("t2", now.Unix()))), now); !ok {
t.Fatalf("good tariff: %s", msg)
}
b, _ := os.ReadFile(filepath.Join(l.cfg.AgentState, "tariff.json"))
if !strings.Contains(string(b), `"id":"t2"`) {
t.Errorf("tariff.json: %s", b)
}
for name, c := range map[string]struct {
cmd command
want string
}{
"other key": {cmd("tariff", bundleArgs(t, other, tariff("t3", now.Unix()))), "bad bundle signature"},
"kind": {cmd("model", bundleArgs(t, k, tariff("t3", now.Unix()))), `a "tariff" bundle, not "model"`},
"older": {cmd("tariff", bundleArgs(t, k, tariff("t1", now.Add(-time.Hour).Unix()))), "older than the one the agent has (t2)"},
"no sig": {cmd("tariff", map[string]string{"bundle": "eyJ2IjoxfQ=="}), "bundle and sig: base64 needed"},
} {
if ok, msg := l.bundleCmd(c.cmd, now); ok || !strings.HasSuffix(msg, c.want) {
t.Errorf("%s: %v %q", name, ok, msg)
}
}
elsewhere := tariff("t4", now.Unix())
elsewhere["site"] = strings.Repeat("cd", 16)
if ok, msg := l.bundleCmd(cmd("tariff", bundleArgs(t, k, elsewhere)), now); ok || !strings.HasSuffix(msg, "not for this site") {
t.Errorf("other site: %v %q", ok, msg)
}
expired := tariff("t5", now.Unix())
expired["expires"] = now.Add(-time.Minute).Unix()
if ok, msg := l.bundleCmd(cmd("tariff", bundleArgs(t, k, expired)), now); ok || !strings.HasSuffix(msg, "expired") {
t.Errorf("expired: %v %q", ok, msg)
}
// a model for every site ("*"); a tariff for every site is not taken
model := map[string]any{"v": 1, "kind": "model", "id": "m1", "site": "*", "issued": now.Unix(), "step_s": 3600}
if ok, msg := l.bundleCmd(cmd("model", bundleArgs(t, k, model)), now); !ok {
t.Errorf("shared model: %s", msg)
}
all := tariff("t6", now.Unix())
all["site"] = "*"
if ok, _ := l.bundleCmd(cmd("tariff", bundleArgs(t, k, all)), now); ok {
t.Error("a tariff for every site was taken")
}
// a building's flats (its own box): for this site only
flats := map[string]any{"v": 1, "kind": "flats", "id": "f1", "site": site, "issued": now.Unix(),
"expires": now.Add(time.Hour).Unix(), "flats": []map[string]any{{"id": "w1", "label": "Flat 1"}}}
if ok, msg := l.bundleCmd(cmd("flats", bundleArgs(t, k, flats)), now); !ok {
t.Errorf("flats: %s", msg)
}
if b, _ := os.ReadFile(filepath.Join(l.cfg.AgentState, "flats.json")); !strings.Contains(string(b), `"label":"Flat 1"`) {
t.Errorf("flats.json: %s", b)
}
// the devices' protection: no expiry; another site's refused
acl := map[string]any{"v": 1, "kind": "acl", "id": "a1", "site": site, "issued": now.Unix(), "expires": 0,
"entries": []map[string]any{{"target": "device:meter-1", "level": "sealed", "custodian": "metering_operator"}}}
if ok, msg := l.bundleCmd(cmd("acl", bundleArgs(t, k, acl)), now); !ok {
t.Errorf("acl: %s", msg)
}
if b, _ := os.ReadFile(filepath.Join(l.cfg.AgentState, "acl.json")); !strings.Contains(string(b), `"level":"sealed"`) {
t.Errorf("acl.json: %s", b)
}
acl["site"], acl["id"], acl["issued"] = strings.Repeat("cd", 16), "a2", now.Unix()+1
if ok, _ := l.bundleCmd(cmd("acl", bundleArgs(t, k, acl)), now); ok {
t.Error("another site's acl stored")
}
// no certificate on the box: refused, not crashed
l.cfg.BundleCert = filepath.Join(t.TempDir(), "missing.pem")
if ok, msg := l.bundleCmd(cmd("tariff", bundleArgs(t, k, tariff("t7", now.Unix()))), now); ok || !strings.HasPrefix(msg, "no bundle certificate") {
t.Errorf("no cert: %v %q", ok, msg)
}
}
func TestAgentPublishLimits(t *testing.T) {
lc := &local{}
now := time.Now()
if !lc.allow("plan", now) || lc.allow("plan", now.Add(4*time.Minute)) || !lc.allow("plan", now.Add(5*time.Minute)) {
t.Error("plans: at most every 5 minutes")
}
n := 0
for i := 0; i < 200; i++ {
if lc.allow("action", now.Add(time.Duration(i)*time.Second)) {
n++
}
}
if n != actionsPerHour {
t.Errorf("actions in an hour: %d", n)
}
if !lc.allow("action", now.Add(61*time.Minute)) {
t.Error("actions after an hour")
}
if !lc.allow("inventory", now) || lc.allow("inventory", now.Add(9*time.Minute)) || !lc.allow("inventory", now.Add(10*time.Minute)) {
t.Error("inventory: at most every 10 minutes")
}
}
+272
View File
@@ -0,0 +1,272 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
// The paths to the platform (docs/direct-link.md): an ordered list of
// devices URLs. The direct ones (CANTABILE_DEVICES_DIRECT: DNS-only names
// whose TLS ends in Cantabile's own cluster, not at Cloudflare) come first
// and are pinned: the server's chain must lead to Cantabile's devices CA
// (CANTABILE_DEVICES_CA) and/or hold one of the pinned keys
// (CANTABILE_DEVICES_SPKI). CANTABILE_DEVICES_URL comes last, verified as any
// web site (today: the Cloudflare tunnel). Without a direct URL the link
// works exactly as before.
//
// A session uses one path for enrolment, renewal and NATS. A path that cannot
// be reached (connection, TLS or pin failure, 502-504) passes the session to
// the next one at once; on a fallback the link checks the direct paths every
// directRetry and goes back to the first one that answers.
package main
import (
"context"
"crypto/sha256"
"crypto/tls"
"crypto/x509"
"encoding/base64"
"errors"
"fmt"
"log/slog"
"net"
"net/http"
"net/url"
"os"
"strings"
"time"
)
// directRetry: how often a session on a fallback checks the direct paths.
var directRetry = 30 * time.Minute
type endpoint struct {
URL string // https://host[:port], no trailing slash
Kind string // "direct" (pinned), "fallback" (after a direct one), "default" (the only one)
tls *tls.Config // nil: the system's roots, as any web site
client *http.Client
}
func (e *endpoint) host() string {
u, err := url.Parse(e.URL)
if err != nil {
return ""
}
return strings.ToLower(u.Hostname())
}
// hostPort: host:port of the endpoint (443 by default).
func (e *endpoint) hostPort() string {
u, err := url.Parse(e.URL)
if err != nil {
return ""
}
if u.Port() != "" {
return u.Host
}
return net.JoinHostPort(u.Hostname(), "443")
}
// splitList: a list in an environment variable, by commas or white space.
func splitList(s string) []string {
return strings.FieldsFunc(s, func(r rune) bool { return r == ',' || r == ' ' || r == '\n' || r == '\t' })
}
// pinnedTLS: TLS for a direct path. With a CA, only that CA is trusted (not
// the system's); with SPKI pins (base64 of the SHA-256 of a certificate's
// SubjectPublicKeyInfo, as HPKP's), a verified chain must hold one of the
// keys. The host name is checked as always. Neither: an error, as a direct
// path without a pin would trust whoever can get a certificate for the name
// (Cloudflare too, which holds the zone's DNS).
func pinnedTLS(caPEM []byte, spki []string) (*tls.Config, error) {
cfg := &tls.Config{MinVersion: tls.VersionTLS12}
if len(caPEM) > 0 {
pool := x509.NewCertPool()
if !pool.AppendCertsFromPEM(caPEM) {
return nil, errors.New("devices CA: no certificate in the PEM")
}
cfg.RootCAs = pool
}
pins := map[string]bool{}
for _, p := range spki {
b, err := base64.StdEncoding.DecodeString(p)
if err != nil || len(b) != sha256.Size {
return nil, fmt.Errorf("SPKI pin %q: base64 of a SHA-256", p)
}
pins[string(b)] = true
}
if cfg.RootCAs == nil && len(pins) == 0 {
return nil, errors.New("a direct path needs the devices CA or an SPKI pin")
}
if len(pins) > 0 {
cfg.VerifyConnection = func(cs tls.ConnectionState) error {
for _, chain := range cs.VerifiedChains {
for _, c := range chain {
if sum := sha256.Sum256(c.RawSubjectPublicKeyInfo); pins[string(sum[:])] {
return nil
}
}
}
return errors.New("no pinned key in the server's certificate chain")
}
}
return cfg, nil
}
func newEndpoint(raw, kind string, tc *tls.Config) *endpoint {
tr := http.DefaultTransport.(*http.Transport).Clone()
if tc != nil {
tr.TLSClientConfig = tc.Clone()
}
return &endpoint{URL: strings.TrimRight(raw, "/"), Kind: kind, tls: tc,
client: &http.Client{Timeout: 60 * time.Second, Transport: tr}}
}
// endpoints: the paths in order. A direct URL that cannot be pinned is left
// out (logged): the link then works as before, on CANTABILE_DEVICES_URL.
func endpoints(cfg config) []*endpoint {
var eps []*endpoint
if len(cfg.Direct) > 0 {
ca, _ := os.ReadFile(cfg.DirectCA)
tc, err := pinnedTLS(ca, cfg.DirectSPKI)
if err != nil {
slog.Error("direct paths left out", "urls", cfg.Direct, "error", err)
} else {
for _, u := range cfg.Direct {
if !strings.HasPrefix(u, "https://") {
slog.Error("direct path left out: not https", "url", u)
continue
}
eps = append(eps, newEndpoint(u, "direct", tc))
}
}
}
fb := strings.TrimRight(cfg.URL, "/")
for _, e := range eps {
if e.URL == fb { // no fallback: CANTABILE_DEVICES_URL is a direct path too
return eps
}
}
kind := "default"
if len(eps) > 0 {
kind = "fallback"
}
return append(eps, newEndpoint(fb, kind, nil))
}
// pathError: the path did not carry the request (nothing reached the
// platform, or a proxy on the way said so); the next path may.
type pathError struct{ err error }
func (e pathError) Error() string { return e.err.Error() }
func (e pathError) Unwrap() error { return e.err }
func isPathError(err error) bool {
var p pathError
return errors.As(err, &p)
}
// natsURL: the NATS URL the platform gave, on the session's path. The
// platform names one host (its own default path); if it is one of the
// box's devices hosts, the box uses the host of the path it is on (the
// same Traefik routes /nats on each). Any other host is used as given.
func natsURL(given string, ep *endpoint, all []*endpoint) (string, bool) {
u, err := url.Parse(given)
if err != nil || ep == nil {
return given, false
}
h := strings.ToLower(u.Hostname())
for _, e := range all {
if e.host() == h {
u.Host = ep.hostPort()
return u.String(), true
}
}
return given, h == ep.host()
}
// probe: whether a path answers now (TLS with its pins, then the
// platform's challenge), for a session on a fallback.
func probe(ctx context.Context, ep *endpoint) error {
ctx, cancel := context.WithTimeout(ctx, 20*time.Second)
defer cancel()
req, _ := http.NewRequestWithContext(ctx, "GET", ep.URL+"/api/devices/challenge", nil)
req.Header.Set("User-Agent", "cantabile-link/"+version)
resp, err := ep.client.Do(req)
if err != nil {
return err
}
resp.Body.Close()
if resp.StatusCode != 200 {
return fmt.Errorf("HTTP %d", resp.StatusCode)
}
return nil
}
// ---- the link's side
// ep: the path of the current session (nil before the first; tests).
func (l *link) ep() *endpoint { return l.cur.Load() }
func (l *link) base() string {
if e := l.ep(); e != nil {
return e.URL
}
return l.cfg.URL
}
func (l *link) client() *http.Client {
if e := l.ep(); e != nil {
return e.client
}
return httpc
}
// pathInfo: for the heartbeat (the console shows which path a box uses).
func (l *link) pathInfo() map[string]any {
e := l.ep()
if e == nil {
return nil
}
return map[string]any{"kind": e.Kind, "host": e.host()}
}
// errBackToDirect: a session on a fallback ends because a direct path
// answers again; the next one starts at once on it.
var errBackToDirect = errors.New("a direct path answers again")
// session: the paths in order until one carries the session. A session that
// got connected and ended is not passed on (the loop starts again from the
// first path).
func (l *link) session(ctx context.Context) error {
if len(l.eps) == 0 {
l.eps = endpoints(l.cfg)
}
var err error
for i, ep := range l.eps {
l.cur.Store(ep)
err = l.sessionOn(ctx, i)
if l.connected || !isPathError(err) || ctx.Err() != nil {
return err
}
if i < len(l.eps)-1 {
slog.Warn("path failed: trying the next", "url", ep.URL, "kind", ep.Kind, "error", err, "next", l.eps[i+1].URL)
}
}
return err
}
// betterPath: a ticker's channel (nil on the first path) and the check that
// one of the paths before index i answers.
func (l *link) betterPath(ctx context.Context, i int) (<-chan time.Time, func() bool, func()) {
if i == 0 {
return nil, func() bool { return false }, func() {}
}
t := time.NewTicker(jitter(directRetry))
return t.C, func() bool {
for _, e := range l.eps[:i] {
if err := probe(ctx, e); err == nil {
slog.Info("going back to a better path", "url", e.URL, "kind", e.Kind)
return true
} else {
slog.Info("path still down", "url", e.URL, "error", err)
}
}
return false
}, t.Stop
}
+288
View File
@@ -0,0 +1,288 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"context"
"crypto/ecdsa"
"crypto/elliptic"
"crypto/rand"
"crypto/sha256"
"crypto/tls"
"crypto/x509"
"crypto/x509/pkix"
"encoding/base64"
"encoding/pem"
"errors"
"math/big"
"net"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"sync/atomic"
"testing"
"time"
"github.com/nats-io/nats.go"
"github.com/nats-io/nkeys"
)
// testCA: a CA and a leaf for 127.0.0.1 signed by it.
func testCA(t *testing.T, name string) (caPEM []byte, leaf tls.Certificate, leafCert *x509.Certificate) {
t.Helper()
ck, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
ct := &x509.Certificate{SerialNumber: big.NewInt(1), Subject: pkix.Name{CommonName: name},
NotBefore: time.Now().Add(-time.Hour), NotAfter: time.Now().Add(time.Hour),
IsCA: true, BasicConstraintsValid: true, KeyUsage: x509.KeyUsageCertSign}
cder, err := x509.CreateCertificate(rand.Reader, ct, ct, &ck.PublicKey, ck)
if err != nil {
t.Fatal(err)
}
ca, _ := x509.ParseCertificate(cder)
lk, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
lt := &x509.Certificate{SerialNumber: big.NewInt(2), Subject: pkix.Name{CommonName: "devices"},
NotBefore: time.Now().Add(-time.Hour), NotAfter: time.Now().Add(time.Hour),
IPAddresses: []net.IP{net.ParseIP("127.0.0.1")}, ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
KeyUsage: x509.KeyUsageDigitalSignature}
lder, err := x509.CreateCertificate(rand.Reader, lt, ca, &lk.PublicKey, ck)
if err != nil {
t.Fatal(err)
}
leafCert, _ = x509.ParseCertificate(lder)
return pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: cder}),
tls.Certificate{Certificate: [][]byte{lder}, PrivateKey: lk}, leafCert
}
func spki(c *x509.Certificate) string {
s := sha256.Sum256(c.RawSubjectPublicKeyInfo)
return base64.StdEncoding.EncodeToString(s[:])
}
// platform: a fake devices API (challenge, enrol) giving the NATS URL nurl.
func platform(nurl string) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path == "/api/devices/challenge" {
w.Write([]byte(`{"challenge":"c","bits":0,"scrypt":{"n":2,"r":1,"p":1,"len":8,"salt":"s"}}`))
return
}
w.Write([]byte(`{"box":"x","jwt":"j","nats":"` + nurl + `","renew_after":3600}`))
})
}
func pinnedServer(t *testing.T, leaf tls.Certificate, h http.Handler) *httptest.Server {
srv := httptest.NewUnstartedServer(h)
srv.TLS = &tls.Config{Certificates: []tls.Certificate{leaf}}
srv.StartTLS()
t.Cleanup(srv.Close)
return srv
}
// The direct path trusts only the devices CA, and with SPKI pins only the
// pinned keys; a web PKI certificate (here httptest's) is refused.
func TestPinnedTLS(t *testing.T) {
ca, leaf, leafCert := testCA(t, "Cantabile Devices CA")
other, _, otherLeaf := testCA(t, "someone else")
srv := pinnedServer(t, leaf, platform("wss://x/nats"))
for _, c := range []struct {
name string
ca []byte
pins []string
ok bool
}{
{"our CA", ca, nil, true},
{"another CA", other, nil, false},
{"our CA and the leaf's key", ca, []string{spki(leafCert)}, true},
{"our CA, the next key pinned only", ca, []string{spki(otherLeaf)}, false},
{"both CAs (rotation)", append(append([]byte{}, other...), ca...), nil, true},
} {
tc, err := pinnedTLS(c.ca, c.pins)
if err != nil {
t.Fatalf("%s: %v", c.name, err)
}
err = probe(context.Background(), newEndpoint(srv.URL, "direct", tc))
if (err == nil) != c.ok {
t.Errorf("%s: %v", c.name, err)
}
}
if _, err := pinnedTLS(nil, nil); err == nil {
t.Error("a direct path without a pin taken")
}
if _, err := pinnedTLS(nil, []string{"short"}); err == nil {
t.Error("a bad pin taken")
}
// httptest's own certificate (a CA the box does not pin)
plain := httptest.NewTLSServer(platform("wss://x/nats"))
defer plain.Close()
tc, _ := pinnedTLS(ca, nil)
if probe(context.Background(), newEndpoint(plain.URL, "direct", tc)) == nil {
t.Error("an unpinned server taken")
}
}
func TestEndpointsConfig(t *testing.T) {
eps := endpoints(config{URL: "https://devices.cantabile.cloud"})
if len(eps) != 1 || eps[0].Kind != "default" || eps[0].tls != nil {
t.Fatalf("default: %+v", eps)
}
// a direct URL without its CA or pins is left out: as before
eps = endpoints(config{URL: "https://devices-cf.example", Direct: []string{"https://devices.example"}, DirectCA: "/nonexistent"})
if len(eps) != 1 || eps[0].Kind != "default" {
t.Fatalf("unpinned direct: %+v", eps)
}
ca, _, _ := testCA(t, "ca")
p := filepath.Join(t.TempDir(), "devices-ca.pem")
os.WriteFile(p, ca, 0o644)
eps = endpoints(config{URL: "https://devices-cf.example/", Direct: splitList("https://devices.example, http://plain.example"), DirectCA: p})
if len(eps) != 2 || eps[0].Kind != "direct" || eps[0].tls == nil || eps[1].Kind != "fallback" || eps[1].URL != "https://devices-cf.example" {
t.Fatalf("direct + fallback: %+v", eps)
}
// without Cloudflare: CANTABILE_DEVICES_URL is the direct path, pinned
eps = endpoints(config{URL: "https://devices.example", Direct: []string{"https://devices.example"}, DirectCA: p})
if len(eps) != 1 || eps[0].Kind != "direct" || eps[0].tls == nil {
t.Fatalf("direct only: %+v", eps)
}
}
func TestNatsURL(t *testing.T) {
direct := newEndpoint("https://devices.example", "direct", nil)
alt := newEndpoint("https://devices2.example:8443", "direct", nil)
cf := newEndpoint("https://devices-cf.example", "fallback", nil)
all := []*endpoint{direct, alt, cf}
for _, c := range []struct {
given string
ep *endpoint
want string
on bool
}{
{"wss://devices-cf.example:443/nats", direct, "wss://devices.example:443/nats", true},
{"wss://devices-cf.example:443/nats", alt, "wss://devices2.example:8443/nats", true},
{"wss://devices.example:443/nats", cf, "wss://devices-cf.example:443/nats", true},
{"wss://nats.elsewhere:443/nats", direct, "wss://nats.elsewhere:443/nats", false},
} {
got, on := natsURL(c.given, c.ep, all)
if got != c.want || on != c.on {
t.Errorf("%s on %s: %s %v", c.given, c.ep.URL, got, on)
}
}
}
func testLink(t *testing.T, eps ...*endpoint) *link {
dir := t.TempDir()
kp, _ := nkeys.CreateUser()
return &link{cfg: config{State: dir, Claim: filepath.Join(dir, "claim-code")}, kp: kp, id: "x", eps: eps}
}
var errStop = errors.New("test: stop")
// stubNATS: records the URL and options nats.Connect would get first (a
// connection error passes the session to the next path).
func stubNATS(t *testing.T) (*string, *nats.Options) {
var url string
o := nats.GetDefaultOptions()
old := connectNATS
connectNATS = func(u string, opts ...nats.Option) (*nats.Conn, error) {
if url == "" { // the first path tried
url = u
for _, f := range opts {
f(&o)
}
}
return nil, errStop
}
t.Cleanup(func() { connectNATS = old })
return &url, &o
}
// The direct path is down (nothing listens): the session goes on through the
// fallback at once, and NATS uses the fallback's host.
func TestSessionFallsBack(t *testing.T) {
ca, _, _ := testCA(t, "ca")
tc, _ := pinnedTLS(ca, nil)
ln, _ := net.Listen("tcp", "127.0.0.1:0")
dead := "https://localhost:" + strings.Split(ln.Addr().String(), ":")[1]
ln.Close()
fb := httptest.NewServer(platform("wss://127.0.0.1:443/nats"))
defer fb.Close()
l := testLink(t, newEndpoint(dead, "direct", tc), newEndpoint(fb.URL, "fallback", nil))
url, o := stubNATS(t)
if err := l.session(context.Background()); !errors.Is(err, errStop) {
t.Fatalf("session: %v", err)
}
if l.ep().Kind != "fallback" || *url != "wss://"+strings.TrimPrefix(fb.URL, "http://")+"/nats" || o.TLSConfig != nil {
t.Fatalf("path %s, nats %s, tls %v", l.ep().Kind, *url, o.TLSConfig != nil)
}
if p := l.pathInfo(); p["kind"] != "fallback" || p["host"] != "127.0.0.1" {
t.Errorf("heartbeat path: %v", p)
}
}
// The direct path answers: enrolment and NATS go there, NATS with its pins,
// though the platform names the Cloudflare host.
func TestSessionDirect(t *testing.T) {
ca, leaf, _ := testCA(t, "ca")
tc, _ := pinnedTLS(ca, nil)
cfHost := "devices-cf.invalid"
srv := pinnedServer(t, leaf, platform("wss://"+cfHost+":443/nats"))
l := testLink(t, newEndpoint(srv.URL, "direct", tc), newEndpoint("https://"+cfHost, "fallback", nil))
url, o := stubNATS(t)
if err := l.session(context.Background()); !errors.Is(err, errStop) {
t.Fatalf("session: %v", err)
}
if *url != "wss://"+strings.TrimPrefix(srv.URL, "https://")+"/nats" {
t.Fatalf("nats %s", *url)
}
if o.TLSConfig == nil || o.TLSConfig.RootCAs == nil || !o.Secure {
t.Error("NATS without the direct path's pins")
}
}
// A NATS refusal that is not about the path (here the stub's) is not passed
// on to the fallback; a platform's 4xx neither.
func TestSessionNoFallbackOnRefusal(t *testing.T) {
ca, leaf, _ := testCA(t, "ca")
tc, _ := pinnedTLS(ca, nil)
srv := pinnedServer(t, leaf, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(403)
w.Write([]byte(`{"error":"revoked"}`))
}))
var fbHit atomic.Bool
fb := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { fbHit.Store(true) }))
defer fb.Close()
l := testLink(t, newEndpoint(srv.URL, "direct", tc), newEndpoint(fb.URL, "fallback", nil))
stubNATS(t)
if err := l.session(context.Background()); isPathError(err) || fbHit.Load() {
t.Fatalf("refusal passed on: %v (fallback asked: %v)", err, fbHit.Load())
}
// a proxy's 502 is the path's
bad := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(502) }))
defer bad.Close()
l = testLink(t, newEndpoint(bad.URL, "direct", nil), newEndpoint(fb.URL, "fallback", nil))
l.session(context.Background())
if !fbHit.Load() {
t.Error("a 502 was not passed on to the fallback")
}
}
// On a fallback the link checks the direct path and goes back once it answers.
func TestBetterPath(t *testing.T) {
ca, leaf, _ := testCA(t, "ca")
tc, _ := pinnedTLS(ca, nil)
srv := pinnedServer(t, leaf, platform("wss://x/nats"))
l := testLink(t, newEndpoint(srv.URL, "direct", tc), newEndpoint("https://cf.invalid", "fallback", nil))
if c, up, stop := l.betterPath(context.Background(), 0); c != nil || up() {
t.Error("the first path looks for a better one")
} else {
stop()
}
c, up, stop := l.betterPath(context.Background(), 1)
defer stop()
if c == nil || !up() {
t.Error("the direct path answers but is not taken back")
}
srv.Close()
if up() {
t.Error("a closed direct path taken back")
}
}
+203
View File
@@ -0,0 +1,203 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
// The hardware fingerprint: a reinstalled box gets a new key and, when its site id came from
// /data or from Home Assistant's instance id, a new site id; fleet recognises
// it from these ids and suggests (or, with the old site's own claim code,
// does) the merge with the earlier site. A hint, never the identity: the
// site's key and claim code stay what proves a site.
//
// Each id is hashed here with its kind ("cantabile-hwid:<kind>:<value>"), so
// no serial or MAC leaves the box; fleet hashes the hashes again with its
// own pepper before it keeps them (reinstall.go). Values boards ship when
// nobody set one are left out (placeholder, junkID).
//
// Sent at enrolment and in the hardware report. In the HA add-on the link
// runs without root and cannot read the DMI ids: addon-run (root) writes
// `cantabile-link fingerprint` to CANTABILE_FINGERPRINT_FILE first.
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"os"
"path/filepath"
"regexp"
"sort"
"strings"
)
// sysRoot: "/" on a box; a directory in the tests.
var sysRoot = "/"
var (
uuidRE = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`)
macRE = regexp.MustCompile(`^([0-9a-f]{2}:){5}[0-9a-f]{2}$`)
)
// dummyUUIDs: product UUIDs boards ship with when nobody set one (also the
// AMI/Gigabyte dummy; the Hub's serial tool knows the same).
var dummyUUIDs = map[string]bool{"03000200-0400-0500-0006-000700080009": true}
// junkID: a value that names no single machine or disk: empty, a
// placeholder, the same character repeated, a counting sequence.
func junkID(v string) bool {
l := strings.ToLower(strings.TrimSpace(v))
if placeholder(l) {
return true
}
plain := strings.NewReplacer("-", "", ":", "", " ", "", ".", "", "_", "").Replace(l)
if len(plain) < 4 || strings.Trim(plain, plain[:1]) == "" {
return true
}
for _, p := range []string{"0123456789", "1234567890", "abcdef", "xxxx", "system product", "system version", "type1",
"default", "unknown", "empty", "invalid", "no asset"} {
if strings.Contains(plain, p) {
return true
}
}
return false
}
func hwHash(kind, v string) string {
sum := sha256.Sum256([]byte("cantabile-hwid:" + kind + ":" + strings.ToLower(strings.TrimSpace(v))))
return hex.EncodeToString(sum[:])
}
func sysFile(p string) string { return strings.TrimSpace(read(filepath.Join(sysRoot, p))) }
// productUUID: the DMI system UUID, when it is a real one.
func productUUID() string {
u := strings.ToLower(sysFile("sys/class/dmi/id/product_uuid"))
plain := strings.ReplaceAll(u, "-", "")
if !uuidRE.MatchString(u) || dummyUUIDs[u] || strings.Trim(plain, "0") == "" || strings.Trim(plain, "f") == "" {
return ""
}
return u
}
// diskSerials: the serials of the box's own disks (not USB, not virtual):
// NVMe and eMMC/SD say it in sysfs; SATA/SCSI disks in their VPD page 0x80
// or their wwid.
func diskSerials() []string {
var out []string
for _, d := range mustGlob(filepath.Join(sysRoot, "sys/block/*")) {
name := filepath.Base(d)
if strings.HasPrefix(name, "loop") || strings.HasPrefix(name, "dm-") || strings.HasPrefix(name, "zram") ||
strings.HasPrefix(name, "sr") || strings.HasPrefix(name, "ram") || strings.HasPrefix(name, "md") {
continue
}
if p, _ := filepath.EvalSymlinks(d); strings.Contains(p, "/usb") || strings.Contains(p, "/virtual/") {
continue
}
s := strings.TrimSpace(read(filepath.Join(d, "device/serial")))
if s == "" {
if b, err := os.ReadFile(filepath.Join(d, "device/vpd_pg80")); err == nil && len(b) > 4 {
s = strings.TrimSpace(strings.Trim(string(b[4:]), "\x00"))
}
}
if s == "" {
s = strings.TrimSpace(read(filepath.Join(d, "device/wwid")))
}
if s == "" {
s = strings.TrimSpace(read(filepath.Join(d, "wwid")))
}
if s != "" && !junkID(s) {
out = append(out, s)
}
}
return out
}
// permanentMACs: the built-in network adapters' own addresses (not USB
// adapters, which move between machines; not random or set addresses; not
// locally administered ones).
func permanentMACs() []string {
var out []string
for _, p := range mustGlob(filepath.Join(sysRoot, "sys/class/net/*")) {
if _, err := os.Stat(filepath.Join(p, "device")); err != nil {
continue // virtual
}
if t := strings.TrimSpace(read(filepath.Join(p, "addr_assign_type"))); t != "" && t != "0" {
continue
}
if sub, err := filepath.EvalSymlinks(filepath.Join(p, "device/subsystem")); err == nil && filepath.Base(sub) == "usb" {
continue
}
mac := strings.ToLower(strings.TrimSpace(read(filepath.Join(p, "address"))))
if !macRE.MatchString(mac) || mac == "00:00:00:00:00:00" || mac == "ff:ff:ff:ff:ff:ff" {
continue
}
if b := mac[1]; strings.ContainsRune("2367abef", rune(b)) { // locally administered (bit 1 of the first byte)
continue
}
out = append(out, mac)
}
return out
}
// fingerprint: {"v": 1, "product_uuid", "board_serial", "product_serial":
// hashes, "disk", "mac": lists of hashes}; kinds without a usable id are
// left out.
func fingerprint() map[string]any {
if f := os.Getenv("CANTABILE_FINGERPRINT_FILE"); f != "" {
var fp map[string]any
if b, err := os.ReadFile(f); err == nil && json.Unmarshal(b, &fp) == nil && fp["v"] != nil {
return fp
}
}
fp := map[string]any{"v": 1}
if u := productUUID(); u != "" {
fp["product_uuid"] = hwHash("product_uuid", u)
}
for _, k := range []string{"board_serial", "product_serial"} {
if v := sysFile("sys/class/dmi/id/" + k); v != "" && !junkID(v) {
fp[k] = hwHash(k, v)
}
}
list := func(kind string, vs []string) {
seen := map[string]bool{}
var hs []string
for _, v := range vs {
if h := hwHash(kind, v); !seen[h] {
seen[h] = true
hs = append(hs, h)
}
}
sort.Strings(hs)
if len(hs) > 8 {
hs = hs[:8]
}
if len(hs) > 0 {
fp[kind] = hs
}
}
list("disk", diskSerials())
list("mac", permanentMACs())
return fp
}
// rawIDs: the same ids in clear, for the box's own screen only (the status
// splash: `cantabile-link hwids`). Never sent.
func rawIDs() [][2]string {
var out [][2]string
if u := productUUID(); u != "" {
out = append(out, [2]string{"Product UUID", u})
}
for _, k := range [][2]string{{"product_serial", "Product serial"}, {"board_serial", "Board serial"}} {
if v := sysFile("sys/class/dmi/id/" + k[0]); v != "" && !junkID(v) {
out = append(out, [2]string{k[1], v})
}
}
for _, d := range diskSerials() {
out = append(out, [2]string{"Disk", d})
}
for _, m := range permanentMACs() {
out = append(out, [2]string{"MAC", m})
}
if s := boxSerial(); s != "" {
out = append(out, [2]string{"Hub serial", s})
}
return out
}
+161
View File
@@ -0,0 +1,161 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"encoding/json"
"os"
"path/filepath"
"strings"
"testing"
)
func put(t *testing.T, root, p, v string) {
t.Helper()
f := filepath.Join(root, p)
os.MkdirAll(filepath.Dir(f), 0o755)
if err := os.WriteFile(f, []byte(v), 0o644); err != nil {
t.Fatal(err)
}
}
// netDev: an adapter with a device (physical) on bus pci or usb.
func netDev(t *testing.T, root, name, mac, assign, bus string) {
d := filepath.Join(root, "sys/class/net", name)
put(t, root, "sys/class/net/"+name+"/address", mac+"\n")
put(t, root, "sys/class/net/"+name+"/addr_assign_type", assign+"\n")
put(t, root, "sys/bus/"+bus+"/.keep", "")
os.MkdirAll(filepath.Join(d, "device"), 0o755)
os.Symlink(filepath.Join(root, "sys/bus", bus), filepath.Join(d, "device/subsystem"))
}
func TestJunkIDs(t *testing.T) {
for _, v := range []string{"", "To be filled by O.E.M.", "Default string", "System Serial Number", "0123456789",
"00000000", "FFFFFFFF", "Not Specified", "None", "N/A", "xxxxxxxx", "1234567890", "Chassis Serial Number",
" ", "AAAAAAAA", "Type1Sku0", "Unknown"} {
if !junkID(v) {
t.Errorf("%q taken as an id", v)
}
}
for _, v := range []string{"5CG1234XYZ", "WD-WX31A1234567", "S3Z9NB0K123456A", "PF2ABC7Q"} {
if junkID(v) {
t.Errorf("%q refused", v)
}
}
}
func TestFingerprint(t *testing.T) {
root := t.TempDir()
old := sysRoot
defer func() { sysRoot = old }()
sysRoot = root
t.Setenv("CANTABILE_FINGERPRINT_FILE", "")
// A machine with junk DMI serials, a dummy-free UUID, one NVMe and one
// SATA disk, a USB stick, a built-in NIC, a USB NIC, a random MAC, a bridge.
put(t, root, "sys/class/dmi/id/product_uuid", "4C4C4544-0000-1000-8000-ABCDEF012345\n")
put(t, root, "sys/class/dmi/id/board_serial", "Default string\n")
put(t, root, "sys/class/dmi/id/product_serial", "5CG1234XYZ\n")
put(t, root, "sys/block/nvme0n1/device/serial", "S3Z9NB0K123456A \n")
put(t, root, "sys/block/sda/device/vpd_pg80", "\x00\x80\x00\x14WD-WX31A1234567\x00")
put(t, root, "sys/block/sdb/device/serial", "0123456789\n") // junk
put(t, root, "sys/block/loop0/device/serial", "LOOPSERIAL1\n")
netDev(t, root, "enp1s0", "00:1E:67:12:34:56", "0", "pci")
netDev(t, root, "enx001122", "00:11:22:33:44:55", "0", "usb")
netDev(t, root, "wlan0", "3a:11:22:33:44:55", "0", "pci") // locally administered
netDev(t, root, "eth9", "00:aa:bb:cc:dd:ee", "1", "pci") // random
put(t, root, "sys/class/net/br0/address", "00:aa:bb:cc:dd:ef\n")
fp := fingerprint()
if fp["product_uuid"] != hwHash("product_uuid", "4c4c4544-0000-1000-8000-abcdef012345") {
t.Fatalf("uuid: %v", fp["product_uuid"])
}
if _, ok := fp["board_serial"]; ok {
t.Fatal("junk board serial sent")
}
if fp["product_serial"] != hwHash("product_serial", "5CG1234XYZ") {
t.Fatal("product serial")
}
disks, _ := fp["disk"].([]string)
if len(disks) != 2 || !contains(disks, hwHash("disk", "S3Z9NB0K123456A")) || !contains(disks, hwHash("disk", "WD-WX31A1234567")) {
t.Fatalf("disks: %v", disks)
}
macs, _ := fp["mac"].([]string)
if len(macs) != 1 || macs[0] != hwHash("mac", "00:1e:67:12:34:56") {
t.Fatalf("macs: %v", macs)
}
b, _ := json.Marshal(fp)
for _, raw := range []string{"5CG1234XYZ", "S3Z9NB0K", "00:1e:67", "4c4c4544"} {
if strings.Contains(strings.ToLower(string(b)), strings.ToLower(raw)) {
t.Fatalf("raw id %q in %s", raw, b)
}
}
// The same ids in clear for the box's own screen (junk left out too).
raw := rawIDs()
want := [][2]string{{"Product UUID", "4c4c4544-0000-1000-8000-abcdef012345"}, {"Product serial", "5CG1234XYZ"}}
if len(raw) != 5 || raw[0] != want[0] || raw[1] != want[1] || raw[4] != [2]string{"MAC", "00:1e:67:12:34:56"} {
t.Fatalf("raw ids: %v", raw)
}
// Dummy and all-zero UUIDs are no ids.
for _, u := range []string{"03000200-0400-0500-0006-000700080009", "00000000-0000-0000-0000-000000000000",
"FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF", "not-a-uuid"} {
put(t, root, "sys/class/dmi/id/product_uuid", u)
if _, ok := fingerprint()["product_uuid"]; ok {
t.Errorf("uuid %s taken", u)
}
}
// The add-on: the file root's `cantabile-link fingerprint` wrote.
f := filepath.Join(t.TempDir(), "fp.json")
os.WriteFile(f, []byte(`{"v":1,"product_uuid":"abc"}`), 0o600)
t.Setenv("CANTABILE_FINGERPRINT_FILE", f)
if fingerprint()["product_uuid"] != "abc" {
t.Fatal("file not used")
}
}
// A box merged into its earlier site keeps that id; the offer is kept.
func TestAdoptAndOffer(t *testing.T) {
st := t.TempDir()
exited := 0
oldExit := exitProcess
defer func() { exitProcess = oldExit }()
exitProcess = func() { exited++ }
t.Setenv("CANTABILE_HUB", "")
cfg := config{State: st, HAUUID: filepath.Join(st, "core.uuid")}
os.WriteFile(cfg.HAUUID, []byte(`{"data":{"uuid":"0123456789abcdef0123456789abcdef"}}`), 0o600)
first, err := siteID(cfg)
if err != nil {
t.Fatal(err)
}
l := &link{cfg: cfg, id: first}
earlier := strings.Repeat("ab", 16)
ok, msg, after := l.reinstallCmd(command{Cmd: "site-moved", Args: map[string]string{"site": earlier}})
if !ok || after == nil {
t.Fatalf("site-moved: %v %s", ok, msg)
}
after()
if exited != 1 {
t.Fatal("no restart")
}
if id, _ := siteID(cfg); id != earlier {
t.Fatalf("site id after the move: %s", id)
}
if ok, _, _ := l.reinstallCmd(command{Cmd: "site-moved", Args: map[string]string{"site": "x"}}); ok {
t.Fatal("bad id taken")
}
ok, _, _ = l.reinstallCmd(command{Cmd: "restore-offer", Args: map[string]string{"offer": `{"from":{"id":"` + earlier + `","name":"Mini PC"},"channel":"dev"}`}})
if !ok {
t.Fatal("offer refused")
}
var o map[string]any
b, _ := os.ReadFile(filepath.Join(st, offerFile))
if json.Unmarshal(b, &o) != nil || o["channel"] != "dev" || o["received"] == nil {
t.Fatalf("offer: %s", b)
}
if ok, _, _ := l.reinstallCmd(command{Cmd: "restore-offer", Args: map[string]string{"offer": `{}`}}); ok {
t.Fatal("empty offer taken")
}
}
+18
View File
@@ -0,0 +1,18 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
module git.setti.solutions/daniel/cantabile/edge/link
go 1.26.0
require (
github.com/nats-io/nats.go v1.54.0
github.com/nats-io/nkeys v0.4.16
golang.org/x/crypto v0.58.0
)
require (
github.com/creack/pty v1.1.24 // indirect
github.com/klauspost/compress v1.20.0 // indirect
github.com/nats-io/nuid v1.0.1 // indirect
golang.org/x/sys v0.49.0 // indirect
)
+14
View File
@@ -0,0 +1,14 @@
github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
github.com/klauspost/compress v1.20.0 h1:a3C1ke2ohxFymNlb2HWAHjDeKCI90scRskErZkR0ezA=
github.com/klauspost/compress v1.20.0/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI=
github.com/nats-io/nats.go v1.54.0 h1:vsXoOxjHp/GmPUN+EcI7uOf/uB+iAP+kEsAFNQN0yzA=
github.com/nats-io/nats.go v1.54.0/go.mod h1:y+DZoD1oBOYfZTU681eTUiUjI0vbqYGixNVFHcjHJ0k=
github.com/nats-io/nkeys v0.4.16 h1:rd5oAuLOb8mnAycB0xleuEBNS1pVVnN0fv/FF34Eypg=
github.com/nats-io/nkeys v0.4.16/go.mod h1:llLgWoI0o4z/Q57q2R1kHfmocyhGV6VG/U18Glg1Afs=
github.com/nats-io/nuid v1.0.1 h1:5iA8DT8V7q8WK2EScv2padNa/rTESc1KdnPw4TC2paw=
github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
golang.org/x/crypto v0.58.0 h1:COkYLr4k7nDI4r6QtMML2AfzeIswWHAJthLS6K/M/54=
golang.org/x/crypto v0.58.0/go.mod h1:Xh+kl5A+M0gMiWDytH2Hhr5Z7WbNCpv/eB/EFgfSk+w=
golang.org/x/sys v0.49.0 h1:XbzkgYJHdqh/8m2Uu0W/dQv8nktxx4BFHp1M0gROTXA=
golang.org/x/sys v0.49.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
+154
View File
@@ -0,0 +1,154 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
// Relayed grid-operator orders (2026-10-29): a building
// never makes an emergency command of its own, but may relay one a grid
// operator gave its connection (§14a dimming), with proof of its source.
// The proof travels in the `building` command's args when its level is
// "emergency":
//
// registration, registration_sig Cantabile's registration of the grid
// operator: a JSON {"v":1,"kind":"grid-operator","id","operator",
// "name","area","key": PEM public key,"issued","expires"} signed
// with the BUNDLE key (the box trusts only that key's registrations)
// order, order_sig the grid operator's order: a JSON {"v":1,
// "kind":"grid-order","id","operator","connection","limit_w",
// "from","until","issued"} signed with the operator's key
// connection the building's grid connection the order is for
//
// The link checks both signatures, that the order is the registered
// operator's, for this connection, in force (not over, from ≤ until ≤ from
// + 24 h) and that the command's window and limit stay inside the order's;
// then it passes the command on with the proof replaced by
// "proof": "verified:<operator>:<order id>" (the agent takes an emergency
// only with it). Without valid proof the command is refused.
import (
"crypto"
"crypto/x509"
"encoding/base64"
"encoding/json"
"encoding/pem"
"errors"
"fmt"
"strconv"
"time"
)
type gridRegistration struct {
V int `json:"v"`
Kind string `json:"kind"`
ID string `json:"id"`
Operator string `json:"operator"`
Name string `json:"name"`
Area string `json:"area"`
Key string `json:"key"`
Issued int64 `json:"issued"`
Expires int64 `json:"expires"`
}
type gridOrder struct {
V int `json:"v"`
Kind string `json:"kind"`
ID string `json:"id"`
Operator string `json:"operator"`
Connection string `json:"connection"`
LimitW float64 `json:"limit_w"`
From int64 `json:"from"`
Until int64 `json:"until"`
Issued int64 `json:"issued"`
}
func b64(args map[string]string, k string) ([]byte, error) {
b, err := base64.StdEncoding.DecodeString(args[k])
if err != nil || len(b) == 0 {
return nil, fmt.Errorf("%s: base64 needed", k)
}
if len(b) > 16<<10 {
return nil, fmt.Errorf("%s: too large", k)
}
return b, nil
}
// checkGridProof: the proof in an emergency `building` command's args,
// checked against the bundle key (Cantabile's registrations). On success
// the proof args are replaced by "proof".
func checkGridProof(bundleKey crypto.PublicKey, args map[string]string, now time.Time) error {
var parts [4][]byte
for i, k := range []string{"registration", "registration_sig", "order", "order_sig"} {
b, err := b64(args, k)
if err != nil {
return err
}
parts[i] = b
}
if !verify(bundleKey, parts[0], parts[1]) {
return errors.New("the grid operator's registration is not Cantabile's")
}
var reg gridRegistration
if json.Unmarshal(parts[0], &reg) != nil || reg.V != 1 || reg.Kind != "grid-operator" || reg.Operator == "" {
return errors.New("not a v1 grid-operator registration")
}
if reg.Expires != 0 && now.Unix() >= reg.Expires {
return errors.New("the grid operator's registration expired")
}
blk, _ := pem.Decode([]byte(reg.Key))
if blk == nil {
return errors.New("the registration's key is not PEM")
}
opKey, err := x509.ParsePKIXPublicKey(blk.Bytes)
if err != nil {
return fmt.Errorf("the registration's key: %v", err)
}
if !verify(opKey, parts[2], parts[3]) {
return errors.New("the order is not signed by " + reg.Operator)
}
var o gridOrder
if json.Unmarshal(parts[2], &o) != nil || o.V != 1 || o.Kind != "grid-order" {
return errors.New("not a v1 grid order")
}
switch {
case o.Operator != reg.Operator:
return errors.New("the order names another operator")
case args["connection"] == "" || o.Connection != args["connection"]:
return errors.New("the order is for another grid connection")
case !(o.From < o.Until && o.Until <= o.From+86400):
return errors.New("the order's window is not from < until ≤ from + 24 h")
case now.Unix() >= o.Until:
return errors.New("the order is over")
case o.Issued > now.Add(time.Hour).Unix():
return errors.New("the order is issued in the future")
}
from, e1 := strconv.ParseInt(args["from"], 10, 64)
until, e2 := strconv.ParseInt(args["until"], 10, 64)
val, e3 := strconv.ParseFloat(args["value"], 64)
switch {
case e1 != nil || e2 != nil || e3 != nil:
return errors.New("from, until and value needed")
case args["control"] != "load_limit":
return errors.New("a relayed order only limits the load (control load_limit)")
case from < o.From || until > o.Until:
return errors.New("the command's window is outside the order's")
case val < 0 || val > o.LimitW:
return errors.New("the command's limit is above the order's")
}
for _, k := range []string{"registration", "registration_sig", "order", "order_sig"} {
delete(args, k)
}
args["proof"] = "verified:" + reg.Operator + ":" + o.ID
return nil
}
// buildingCmd: a `building` command; an emergency one only with its proof.
func (l *link) buildingCmd(c *command, now time.Time) error {
if c.Args["level"] != "emergency" {
delete(c.Args, "proof") // only the link sets it
return nil
}
key, err := l.bundleCert()
if err != nil {
return fmt.Errorf("no bundle certificate to check the grid operator's proof: %v", err)
}
return checkGridProof(key, c.Args, now)
}
+93
View File
@@ -0,0 +1,93 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"crypto/ecdsa"
"crypto/elliptic"
"crypto/rand"
"crypto/sha256"
"crypto/x509"
"encoding/base64"
"encoding/json"
"encoding/pem"
"fmt"
"strings"
"testing"
"time"
)
func gridSigned(t *testing.T, k *ecdsa.PrivateKey, v any) (string, string) {
data, _ := json.Marshal(v)
sum := sha256.Sum256(data)
sig, err := ecdsa.SignASN1(rand.Reader, k, sum[:])
if err != nil {
t.Fatal(err)
}
return base64.StdEncoding.EncodeToString(data), base64.StdEncoding.EncodeToString(sig)
}
// gridArgs: an emergency `building` command as fleet relays a grid order.
func gridArgs(t *testing.T, bundleKey, opKey *ecdsa.PrivateKey, now time.Time, edit func(reg, order map[string]any, args map[string]string)) map[string]string {
der, _ := x509.MarshalPKIXPublicKey(&opKey.PublicKey)
reg := map[string]any{"v": 1, "kind": "grid-operator", "id": "r1", "operator": "netz-berlin", "name": "Stromnetz Berlin",
"area": "DE-BER", "key": string(pem.EncodeToMemory(&pem.Block{Type: "PUBLIC KEY", Bytes: der})),
"issued": now.Unix() - 60, "expires": now.Unix() + 86400}
order := map[string]any{"v": 1, "kind": "grid-order", "id": "o1", "operator": "netz-berlin", "connection": "MALO-1",
"limit_w": 4200.0, "from": now.Unix() - 60, "until": now.Unix() + 3600, "issued": now.Unix() - 60}
args := map[string]string{"v": "1", "id": "c1", "building": "b1", "level": "emergency", "control": "load_limit",
"value": "1400", "from": fmt.Sprint(now.Unix()), "until": fmt.Sprint(now.Unix() + 1800), "connection": "MALO-1"}
if edit != nil {
edit(reg, order, args)
}
args["registration"], args["registration_sig"] = gridSigned(t, bundleKey, reg)
signer := opKey
if forger, ok := order["_signer"].(*ecdsa.PrivateKey); ok {
signer = forger
delete(order, "_signer")
}
args["order"], args["order_sig"] = gridSigned(t, signer, order)
return args
}
func TestGridProof(t *testing.T) {
now := time.Now()
bk, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
ok, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
other, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
a := gridArgs(t, bk, ok, now, nil)
if err := checkGridProof(&bk.PublicKey, a, now); err != nil {
t.Fatalf("valid proof refused: %v", err)
}
if a["proof"] != "verified:netz-berlin:o1" || a["order"] != "" || a["registration"] != "" {
t.Errorf("proof not replaced: %v", a)
}
for name, c := range map[string]struct {
edit func(reg, order map[string]any, args map[string]string)
key *ecdsa.PrivateKey // signs the order
bk *ecdsa.PrivateKey // signs the registration
want string
}{
"registration not Cantabile's": {nil, ok, other, "not Cantabile's"},
"order not the operator's": {func(_, o map[string]any, _ map[string]string) { o["_signer"] = other }, ok, bk, "not signed by"},
"another connection": {func(_, _ map[string]any, a map[string]string) { a["connection"] = "MALO-2" }, ok, bk, "another grid connection"},
"limit above the order's": {func(_, _ map[string]any, a map[string]string) { a["value"] = "5000" }, ok, bk, "above the order"},
"window outside": {func(_, _ map[string]any, a map[string]string) { a["until"] = fmt.Sprint(now.Unix() + 7200) }, ok, bk, "outside the order"},
"order over": {func(_, o map[string]any, _ map[string]string) { o["until"] = now.Unix() - 1 }, ok, bk, "order is over"},
"not a load limit": {func(_, _ map[string]any, a map[string]string) { a["control"] = "thermostat_cap" }, ok, bk, "load_limit"},
"registration expired": {func(r, _ map[string]any, _ map[string]string) { r["expires"] = now.Unix() - 1 }, ok, bk, "expired"},
"order names another operator": {func(_, o map[string]any, _ map[string]string) { o["operator"] = "someone" }, ok, bk, "another operator"},
} {
a := gridArgs(t, c.bk, c.key, now, c.edit)
err := checkGridProof(&bk.PublicKey, a, now)
if err == nil || !strings.Contains(err.Error(), c.want) {
t.Errorf("%s: %v, want %q", name, err, c.want)
}
}
// an emergency without any proof
if err := checkGridProof(&bk.PublicKey, map[string]string{"level": "emergency"}, now); err == nil {
t.Error("no proof accepted")
}
}
+551
View File
@@ -0,0 +1,551 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
// The Cantabile Hub (CANTABILE_HUB=1): the link runs on the box itself
// (cantabile-link.service, root) and does what the box's console
// needs: status and hardware
// reports, the box's event log, the console's commands on the box
// (hubcmd.go), the remote terminal (terminal.go) and support in the owner's
// panel (panel.go). In the Home Assistant add-on none of this runs: there
// the link has no box of its own.
import (
"bufio"
"bytes"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"os"
"os/exec"
"path/filepath"
"regexp"
"sort"
"strconv"
"strings"
"syscall"
"time"
"github.com/nats-io/nkeys"
)
const (
statusEvery = 5 * time.Minute
runDir = "/run/cantabile"
runState = runDir + "/agent.json" // the link's state for the panel and logs ("box", "connected")
eventsFile = "/data/log/events" // the box's event log (/usr/lib/cantabile/logs)
logsTool = "/usr/lib/cantabile/logs" // events, support bundles
espRecovery = "/boot/efi/recovery"
grubenv = "/boot/efi/grub/grubenv"
hubState = "/data/cantabile/edge/link" // the link's state on the Hub (cantabile-link.service)
boxStatus = "/run/cantabile-status/status.json" // cantabile-status: disk_health (SMART, daily)
)
func isHub() bool { return os.Getenv("CANTABILE_HUB") == "1" }
func read(p string) string {
b, _ := os.ReadFile(p)
return strings.TrimSpace(string(b))
}
func jsonFile(p string) map[string]any {
var m map[string]any
b, _ := os.ReadFile(p)
json.Unmarshal(b, &m)
return m
}
func mustGlob(p string) []string { m, _ := filepath.Glob(p); return m }
// event: a line in the box's event log (the owner sees it in the panel).
func event(kind, msg string) { exec.Command(logsTool, "event", kind, msg).Run() }
// osVersion: the Hub's release (IMAGE_VERSION in os-release).
func osVersion() string {
m := regexp.MustCompile(`(?m)^IMAGE_VERSION="?([^"\n]*)`).FindStringSubmatch(read("/etc/os-release"))
if m == nil {
return "0.0.0"
}
return m[1]
}
func slot() string {
m := regexp.MustCompile(`rauc\.slot=(\S+)`).FindStringSubmatch(read("/proc/cmdline"))
if m == nil {
return ""
}
return m[1]
}
func uptime() int64 {
f := strings.Fields(read("/proc/uptime"))
if len(f) == 0 {
return 0
}
v, _ := strconv.ParseFloat(f[0], 64)
return int64(v)
}
// setState: /run/cantabile/agent.json: the site id (the
// logs tool signs support requests for it) and whether the platform is
// connected.
func (l *link) setState(connected bool, msg string) {
if !isHub() {
return
}
b, _ := json.Marshal(map[string]any{"box": l.id, "connected": connected, "message": msg, "at": time.Now().Unix()})
os.MkdirAll(runDir, 0o755)
os.WriteFile(runState+".tmp", b, 0o644)
os.Rename(runState+".tmp", runState)
}
// hubHeartbeat: the Hub's heartbeat. "version" is the box's release (the
// console's version column, releases and pushes go by it); the link's own
// build is "link".
func (l *link) hubHeartbeat() map[string]any {
st, _ := updateState(runDir + "/update.json")
return map[string]any{"v": 1, "version": osVersion(), "link": version, "slot": slot(), "uptime_s": uptime(),
"agent": l.loc.connected(), "update": st, "serial": boxSerial(), "setup_done": setupDone(boxConfig)}
}
// boxConfig: the box's settings (the panel's, root only); the link reads
// one flag of it.
var boxConfig = "/data/cantabile/config.json"
// setupDone: the owner finished the setup wizard (the panel's setup_done):
// before that, support cannot open the panel (the console says so).
func setupDone(path string) bool {
done, _ := jsonFile(path)["setup_done"].(bool)
return done
}
// updateState: cantabile-update's state and the release the channel offers
// (update.json in /run). Until its first check after a boot (the timer:
// 2 minutes) there is no file: "not-checked", not null (dev.20's first
// reports after a boot said "state": null).
func updateState(path string) (state, available any) {
if _, err := os.Stat(path); err != nil {
return "not-checked", nil
}
u := jsonFile(path)
return u["state"], u["available"]
}
func memInfo() map[string]int64 {
out := map[string]int64{}
for _, ln := range strings.Split(read("/proc/meminfo"), "\n") {
f := strings.Fields(ln)
if len(f) >= 2 {
n, _ := strconv.ParseInt(f[1], 10, 64)
out[strings.TrimSuffix(f[0], ":")] = n
}
}
return out
}
type cpuSample struct{ busy, total uint64 }
func readCPU() cpuSample {
f := strings.Fields(strings.SplitN(read("/proc/stat"), "\n", 2)[0])
var s cpuSample
if len(f) < 2 {
return s
}
for i, x := range f[1:] {
n, _ := strconv.ParseUint(x, 10, 64)
s.total += n
if i != 3 && i != 4 { // idle, iowait
s.busy += n
}
}
return s
}
func temperature() any {
for _, p := range append(mustGlob("/sys/class/hwmon/hwmon*/temp1_input"), mustGlob("/sys/class/thermal/thermal_zone*/temp")...) {
if v, err := strconv.Atoi(read(p)); err == nil && v > 0 {
return v / 1000
}
}
return nil
}
// wifiState: the box's Wi-Fi as a client of the owner's network (the
// setup network while it is up): mode and signal, never network names.
func wifiState() []map[string]any {
h := jsonFile(runDir + "/hotspot.json")
if h["adapter"] == nil {
return []map[string]any{}
}
w := map[string]any{"network": "Wi-Fi", "mode": h["mode"]}
if ifc, _ := h["adapter"].(string); ifc != "" && h["mode"] == "client" {
if out, err := exec.Command("iw", "dev", ifc, "link").Output(); err == nil {
if m := regexp.MustCompile(`signal:\s*(-?\d+)`).FindStringSubmatch(string(out)); m != nil {
w["signal_dbm"], _ = strconv.Atoi(m[1])
}
}
}
return []map[string]any{w}
}
// status: what the console's box page shows (load, CPU, RAM, temperature,
// disk, Wi-Fi, add-ons, channel, updates), every statusEvery.
func (l *link) status() map[string]any {
now := readCPU()
cpuPct := 0
if d := now.total - l.cpu.total; d > 0 && l.cpu.total > 0 {
cpuPct = int(100 * (now.busy - l.cpu.busy) / d)
}
l.cpu = now
var load []float64
if f := strings.Fields(read("/proc/loadavg")); len(f) >= 3 {
for _, x := range f[:3] {
v, _ := strconv.ParseFloat(x, 64)
load = append(load, v)
}
}
mi := memInfo()
ram := 0
if mi["MemTotal"] > 0 {
ram = int(100 * (mi["MemTotal"] - mi["MemAvailable"]) / mi["MemTotal"])
}
var st syscall.Statfs_t
disk := map[string]any{}
if syscall.Statfs("/data", &st) == nil && st.Blocks > 0 {
disk["data_used_pct"] = int(100 * (st.Blocks - st.Bavail) / st.Blocks)
disk["data_free_mb"] = int64(st.Bavail) * int64(st.Bsize) >> 20
}
var mhz any
if v, err := strconv.Atoi(read("/sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq")); err == nil {
mhz = v / 1000
}
addons := map[string]any{}
if ad, ok := jsonFile(runDir + "/addons.json")["addons"].(map[string]any); ok {
for k, v := range ad {
m, _ := v.(map[string]any)
addons[k] = map[string]any{"version": m["running"], "state": m["state"]}
}
}
ust, uav := updateState(runDir + "/update.json")
ch := read(channelFile)
if ch == "" {
ch = defaultChannel()
}
return map[string]any{"v": 1, "version": osVersion(), "link": version, "slot": slot(), "uptime_s": uptime(),
"load": load, "cpu_pct": cpuPct, "ram_pct": ram, "temp_c": temperature(), "cpu_mhz": mhz, "disk": disk,
"wifi": wifiState(), "addons": addons, "channel": ch,
"update": map[string]any{"state": ust, "available": uav},
// SMART on the box's own disk, as cantabile-status read it (null
// until its first run); fleet's hardware view counts the bad ones.
"disk_health": jsonFile(boxStatus)["disk_health"]}
}
// defaultChannel: the build's channel (scripts/build.sh writes dl.env;
// the update tool reads the same file).
func defaultChannel() string {
m := regexp.MustCompile(`(?m)^CANTABILE_CHANNEL=(stable|beta|dev)$`).FindStringSubmatch(read("/usr/lib/cantabile/dl.env"))
if m == nil {
return "stable"
}
return m[1]
}
// ---- hardware: devices, their drivers, what is missing (IDs and names
// only). Sent at start, daily and when it changes (e.g. a dongle).
func sysRead(dir, name string) string { return read(filepath.Join(dir, name)) }
func driverOf(dev string) string {
if p, err := filepath.EvalSymlinks(filepath.Join(dev, "driver")); err == nil {
return filepath.Base(p)
}
return ""
}
var pciClass = map[string]string{"02": "network", "03": "display", "04": "multimedia", "0c": "serial bus", "01": "storage", "06": "bridge", "08": "system", "11": "signal"}
// enrolModel, enrolVersion: what the site enrols as: on the Hub the machine
// and its release, in the add-on the link.
func enrolModel() string {
if m := dmiModel(); isHub() && m != "" {
return m
}
return "cantabile-edge"
}
func enrolVersion() string {
if isHub() {
return osVersion()
}
return version
}
func cpuModel() string {
for _, ln := range strings.Split(read("/proc/cpuinfo"), "\n") {
if strings.HasPrefix(ln, "model name") {
return strings.TrimSpace(strings.SplitN(ln, ":", 2)[1])
}
}
return ""
}
func dmiModel() string {
v, p := read("/sys/class/dmi/id/sys_vendor"), read("/sys/class/dmi/id/product_name")
return strings.TrimSpace(v + " " + p)
}
// board: the machine's identity from DMI (vendor, board, product, BIOS).
func board() map[string]string {
b := map[string]string{}
for k, f := range map[string]string{"sys_vendor": "sys_vendor", "product": "product_name", "board_vendor": "board_vendor",
"board": "board_name", "bios_vendor": "bios_vendor", "bios_version": "bios_version", "bios_date": "bios_date"} {
if v := strings.TrimSpace(read("/sys/class/dmi/id/" + f)); v != "" {
b[k] = v
}
}
return b
}
// disks: the box's own disks (not USB sticks), with whether they spin.
func disks() []map[string]any {
out := []map[string]any{}
for _, d := range mustGlob("/sys/block/*") {
name := filepath.Base(d)
if strings.HasPrefix(name, "loop") || strings.HasPrefix(name, "dm-") || strings.HasPrefix(name, "zram") || strings.HasPrefix(name, "sr") {
continue
}
if p, _ := filepath.EvalSymlinks(d); strings.Contains(p, "/usb") {
continue
}
sectors, _ := strconv.ParseInt(sysRead(d, "size"), 10, 64)
if sectors == 0 {
continue
}
out = append(out, map[string]any{"name": name, "size_gb": sectors * 512 / 1e9, "model": sysRead(d, "device/model"),
"rotational": sysRead(d, "queue/rotational") == "1"})
}
return out
}
func hardwareReport() map[string]any {
type dev struct {
Bus string `json:"bus"`
ID string `json:"id"` // vendor:device
Class string `json:"class,omitempty"`
Name string `json:"name,omitempty"`
Driver string `json:"driver"`
Modalias []string `json:"modalias,omitempty"` // without a driver: which module would take it
}
var devs []dev
noDriver := []string{}
for _, d := range mustGlob("/sys/bus/pci/devices/*") {
cls := strings.TrimPrefix(sysRead(d, "class"), "0x")
v, p := strings.TrimPrefix(sysRead(d, "vendor"), "0x"), strings.TrimPrefix(sysRead(d, "device"), "0x")
c := cls
if len(cls) >= 2 {
c = pciClass[cls[:2]]
}
x := dev{Bus: "pci", ID: v + ":" + p, Class: c, Driver: driverOf(d)}
if x.Driver == "" {
if m := sysRead(d, "modalias"); m != "" {
x.Modalias = []string{m}
}
}
devs = append(devs, x)
if x.Driver == "" && c != "bridge" && c != "system" && c != "" {
noDriver = append(noDriver, "pci "+x.ID+" ("+c+")")
}
}
for _, d := range mustGlob("/sys/bus/usb/devices/*") {
v, p := sysRead(d, "idVendor"), sysRead(d, "idProduct")
if v == "" || sysRead(d, "bDeviceClass") == "09" { // hubs
continue
}
drivers := map[string]bool{} // on the device's interfaces (<dev>:<cfg>.<if>)
for _, itf := range mustGlob(d + "/" + filepath.Base(d) + ":*") {
if dr := driverOf(itf); dr != "" {
drivers[dr] = true
}
}
var ds []string
for k := range drivers {
ds = append(ds, k)
}
sort.Strings(ds)
x := dev{Bus: "usb", ID: v + ":" + p, Name: strings.TrimSpace(sysRead(d, "manufacturer") + " " + sysRead(d, "product")), Driver: strings.Join(ds, ",")}
if x.Driver == "" {
for _, itf := range mustGlob(d + "/" + filepath.Base(d) + ":*") {
if m := sysRead(itf, "modalias"); m != "" {
x.Modalias = append(x.Modalias, m)
}
}
}
devs = append(devs, x)
if x.Driver == "" {
noDriver = append(noDriver, "usb "+x.ID+" "+x.Name)
}
}
nets := []map[string]any{}
for _, p := range mustGlob("/sys/class/net/*") {
if _, err := os.Stat(p + "/device"); err != nil {
continue // virtual (bridge, containers, loopback)
}
kind := "ethernet"
if _, err := os.Stat(p + "/wireless"); err == nil {
kind = "wifi"
}
bus := "pci"
if sub, err := filepath.EvalSymlinks(p + "/device/subsystem"); err == nil {
bus = filepath.Base(sub)
}
nets = append(nets, map[string]any{"interface": filepath.Base(p), "kind": kind, "bus": bus, "driver": driverOf(p + "/device"),
"link": sysRead(p, "operstate")})
}
// Firmware the kernel asked for and did not find, and failed probes
// (this boot), with the devices they name (hwreason.go).
var klog []string
if out, err := exec.Command("journalctl", "-k", "-b", "--no-pager", "-o", "cat", "--grep", "firmware|probe").Output(); err == nil {
klog = strings.Split(string(out), "\n")
}
kl := parseKernelLog(klog, sysNames("/sys"))
kernel, _ := exec.Command("uname", "-r").Output()
var unresolved []hwDev
for _, d := range devs {
if d.Driver == "" && d.Class != "bridge" && d.Class != "system" && len(d.Modalias) > 0 {
unresolved = append(unresolved, hwDev{Bus: d.Bus, ID: d.ID, Modalias: d.Modalias})
}
}
kroot := "/lib/modules/" + strings.TrimSpace(string(kernel))
resolved := resolveHardware(unresolved, kl.missing, kroot, "/usr/lib/firmware")
explainHardware(resolved, kl, modulesHere(kroot), loadedModules(read("/proc/modules")),
blacklistedModules(modprobeDirs, read("/proc/cmdline")))
return map[string]any{"v": 1, "model": dmiModel(), "serial": boxSerial(), "kernel": strings.TrimSpace(string(kernel)), "devices": devs,
"network": nets, "no_driver": noDriver, "missing_firmware": kl.missing, "disks": disks(),
"hardware": map[string]any{"cpu": cpuModel(), "cores": strings.Count(read("/proc/cpuinfo"), "\nprocessor") + 1,
"ram_mb": memInfo()["MemTotal"] / 1024, "bios": read("/sys/class/dmi/id/bios_version")},
"board": board(), "resolved": resolved, "fingerprint": fingerprint()}
}
// sendHardware: when it changed, or once a day.
func (l *link) sendHardware(force bool) {
r := hardwareReport()
b, _ := json.Marshal(r)
sum := sha256.Sum256(b)
h := hex.EncodeToString(sum[:])
if !force && h == l.hwHash && time.Since(l.hwAt) < 24*time.Hour {
return
}
l.hwHash, l.hwAt = h, time.Now()
l.publish("hardware", r)
}
// sendEvents: new lines of the box's event log (kind, message, time).
func (l *link) sendEvents() {
st, err := os.Stat(eventsFile)
if err != nil {
return
}
size := st.Size()
if size < l.evOff {
l.evOff = 0 // rotated
}
if size == l.evOff {
return
}
f, err := os.Open(eventsFile)
if err != nil {
return
}
defer f.Close()
f.Seek(l.evOff, io.SeekStart)
data, _ := io.ReadAll(io.LimitReader(f, 256<<10))
last := bytes.LastIndexByte(data, '\n')
if last < 0 {
return
}
sc := bufio.NewScanner(bytes.NewReader(data[:last]))
sc.Buffer(make([]byte, 64<<10), 256<<10)
for sc.Scan() {
var e struct{ Time, Kind, Message string }
if json.Unmarshal(sc.Bytes(), &e) == nil && e.Kind != "" {
l.publish("event", map[string]any{"v": 1, "kind": e.Kind, "msg": e.Message, "at": e.Time})
}
}
l.evOff += int64(last + 1)
}
// hubReports: at connection and then every statusEvery (status, hardware
// when it changed), every 20 s the event log's new lines. Ends with done.
func (l *link) hubReports(done <-chan struct{}) {
l.publish("status", l.status())
l.sendHardware(true)
// Events from before this start are not sent again.
if st, err := os.Stat(eventsFile); err == nil && l.evOff == 0 {
l.evOff = st.Size()
}
st, ev := time.NewTicker(statusEvery), time.NewTicker(20*time.Second)
defer st.Stop()
defer ev.Stop()
for {
select {
case <-done:
return
case <-st.C:
l.publish("status", l.status())
l.sendHardware(false)
case <-ev.C:
l.sendEvents()
}
}
}
// ---- cantabile-link sign <text>: a support request signed with the
// site's key (the logs tool); only support-ticket
// texts for this site.
var buildingSignRE = regexp.MustCompile(`^building:[0-9a-f]{32}:[0-9]{1,12}:[0-9a-f]{64}$`)
func signCmd(cfg config, text string) error {
// Called by the logs tool without the service's settings: the Hub's
// state directory (cantabile-link.service) when the default has none.
if _, err := os.Stat(filepath.Join(cfg.State, "seed")); err != nil && os.Getenv("CANTABILE_LINK_STATE") == "" {
cfg.State = hubState
}
id := read(filepath.Join(cfg.State, "site-id"))
if id == "" {
return errors.New("sign: no site id yet")
}
seed, err := os.ReadFile(filepath.Join(cfg.State, "seed"))
if err != nil {
return fmt.Errorf("sign: no key yet: %w", err)
}
sig, err := signFor(id, seed, text)
if err != nil {
return err
}
fmt.Println(sig)
return nil
}
func signFor(id string, seed []byte, text string) (string, error) {
// A support request, or a request to fleet about joining a building
// (the panel: building:<site>:<unix time>:<sha256 hex of the request>,
// fleet joining.go): nothing else is signed with the site's key.
building := buildingSignRE.MatchString(text) && strings.HasPrefix(text, "building:"+id+":")
if !(strings.HasPrefix(text, "support-ticket:"+id+":") || building) || len(text) > 200 {
return "", errors.New("sign: only support-ticket:<this site's id>:... or building:<this site's id>:<time>:<sha256> texts")
}
kp, err := nkeys.FromSeed(bytes.TrimSpace(seed))
if err != nil {
return "", err
}
sig, err := kp.Sign([]byte(text))
if err != nil {
return "", err
}
return base64.StdEncoding.EncodeToString(sig), nil
}
+25
View File
@@ -0,0 +1,25 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"os"
"path/filepath"
"testing"
)
// The heartbeat's setup_done: the panel's flag, false without the file.
func TestSetupDone(t *testing.T) {
p := filepath.Join(t.TempDir(), "config.json")
if setupDone(p) {
t.Fatal("no file: not set up")
}
os.WriteFile(p, []byte(`{"admin": "x", "setup_done": true}`), 0o600)
if !setupDone(p) {
t.Fatal("set up")
}
os.WriteFile(p, []byte(`{"setup_done": "yes"}`), 0o600)
if setupDone(p) {
t.Fatal("not a bool")
}
}
+160
View File
@@ -0,0 +1,160 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
// The console's commands on the Hub:
// updates, restart, rollback, logs to support, add-ons, the update channel,
// the recovery system, a pushed release, the remote terminal and support in
// the panel. Each answers first; a restart comes after the answer is sent.
import (
"fmt"
"os"
"os/exec"
"regexp"
"strings"
"time"
)
const channelFile = "/data/cantabile/update-channel" // read by /usr/lib/cantabile/update
var versionRE = regexp.MustCompile(`^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$`)
func runCmd(name string, args ...string) (string, error) {
out, err := exec.Command(name, args...).CombinedOutput()
s := strings.TrimSpace(string(out))
if len(s) > 300 {
s = s[len(s)-300:]
}
return s, err
}
func reboot() { time.Sleep(5 * time.Second); exec.Command("systemctl", "reboot").Run() }
// hubDo: (handled, ok, message, after). Not handled: the agent's command.
func (l *link) hubDo(c command) (bool, bool, string, func()) {
switch c.Cmd {
case "refresh":
l.publish("hb", l.hubHeartbeat())
l.publish("status", l.status())
l.sendHardware(true)
return true, true, "status sent", nil
case "update-check":
_, err := runCmd("systemctl", "start", "--no-block", "cantabile-update.service")
return true, err == nil, "update check started", nil
case "restart":
event("restart", "restart requested by Cantabile")
return true, true, "restarting in 5 s", reboot
case "rollback":
out, err := runCmd("rauc", "status", "mark-active", "other")
if err != nil {
return true, false, "rollback refused: " + out, nil
}
event("rollback", "rollback requested by Cantabile")
return true, true, "switched to the other slot; restarting in 5 s", reboot
case "collect-logs":
if out, err := runCmd(logsTool, "bundle"); err != nil {
return true, false, "bundle: " + out, nil
}
msg := c.Args["message"]
if msg == "" {
msg = "Logs requested by Cantabile support."
}
out, err := runCmd(logsTool, "upload", msg)
return true, err == nil, out, nil
case "addon":
// Through systemd, as the panel does: an add-on merged in this
// service's own namespace would not be seen by the rest of the box.
args := []string{"--quiet", "--wait", "--pipe", "--collect", "/usr/lib/cantabile/addons", c.Args["op"], c.Args["id"]}
what := c.Args["op"] + " " + c.Args["id"]
if v := c.Args["version"]; v != "" {
if c.Args["op"] != "install" || !versionRE.MatchString(v) {
return true, false, "bad version " + v, nil
}
args, what = append(args, v), what+" "+v
}
out, err := runCmd("systemd-run", args...)
if err != nil {
return true, false, out, nil
}
return true, true, what + ": done", nil
case "channel":
ch := c.Args["channel"]
if ch != "stable" && ch != "beta" && ch != "dev" {
return true, false, "unknown channel", nil
}
if err := os.WriteFile(channelFile, []byte(ch+"\n"), 0o644); err != nil {
return true, false, err.Error(), nil
}
event("channel", "update channel set to "+ch+" by Cantabile")
return true, true, "follows " + ch, nil
case "terminal-open":
ok, msg := l.termOpen(c)
return true, ok, msg, nil
case "panel-open":
ok, msg := l.panelOpen(c)
return true, ok, msg, nil
case "recovery":
ok, msg, after := toRecovery()
return true, ok, msg, after
case "ota-push":
ok, msg := otaPush(c.Args["version"])
return true, ok, msg, nil
}
return false, false, "", nil
}
func hasRecovery() bool {
for _, d := range []string{espRecovery + "-a", espRecovery + "-b", espRecovery} {
if _, err := os.Stat(d + "/vmlinuz"); err == nil {
return true
}
}
return false
}
// toRecovery: the next boot starts the recovery system once (RECOVERY=1,
// hub/recovery/init).
func toRecovery() (bool, string, func()) {
if !hasRecovery() {
return false, "this box has no recovery system", nil
}
if out, err := runCmd("grub-editenv", grubenv, "set", "RECOVERY=1"); err != nil {
return false, "grubenv: " + out, nil
}
exec.Command("sync").Run()
event("recovery", "restart into recovery requested by Cantabile")
return true, "restarting into recovery in 5 s", reboot
}
// otaPush: that release now, whatever the channel and quiet hours, in its
// own unit (the install outlives this answer and the link). One at a time.
func otaPush(v string) (bool, string) {
if !versionRE.MatchString(v) {
return false, "bad version"
}
if st, _ := runCmd("systemctl", "show", "cantabile-update-push", "-p", "ActiveState", "-p", "ExecMainStartTimestamp", "-p", "Description"); st != "" {
p := map[string]string{}
for _, ln := range strings.Split(st, "\n") {
if k, val, ok := strings.Cut(ln, "="); ok {
p[k] = strings.TrimSpace(val)
}
}
switch p["ActiveState"] {
case "active", "activating", "deactivating", "reloading":
was := ""
if f := strings.Fields(p["Description"]); len(f) > 0 {
was = f[len(f)-1]
}
return false, fmt.Sprintf("a push of %s is already running (since %s): wait for it to end, or restart the box to stop it", was, p["ExecMainStartTimestamp"])
case "failed":
runCmd("systemctl", "reset-failed", "cantabile-update-push")
}
}
out, err := runCmd("systemd-run", "--unit=cantabile-update-push", "--description=Cantabile pushed release "+v,
"--collect", "--no-block", "/usr/lib/cantabile/update", "push", v)
if err != nil {
return false, out
}
return true, "installing " + v + " (restarts when done)"
}
+246
View File
@@ -0,0 +1,246 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
// Why a device has no driver. On a Samsung TX-WN the
// report listed the SMBus (pci 1002:4385) and a TUSB3410 (usb 0451:3410)
// without a driver; the full kernel has both drivers: i2c_piix4 was loaded and did not
// take the SMBus (harmless), ti_usb_3410_5052 failed its probe with -2
// because ti_3410.fw is missing. The box knows this; now it says so:
//
// not-loaded a module of this Cantabile matches, it is not loaded
// blacklisted a matching module is blacklisted (modprobe.d, the
// kernel command line) and not loaded
// loaded-not-bound a matching module is loaded, the device is not bound
// probe-failed "probe with driver X failed with error N" for the
// device (error and its meaning)
// needs-firmware the device's driver asked for firmware that was not
// found (the files, when the log names them)
//
// The kernel log names devices by their kernel name (0000:00:14.5, 5-5,
// 5-5:1.0 for a USB interface); sysfs maps them to the report's keys.
import (
"os"
"path/filepath"
"regexp"
"sort"
"strconv"
"strings"
)
// kernelLog: what this boot's kernel log says about firmware and probes.
type kernelLog struct {
missing []string // firmware files not found (sorted)
firmware map[string]string // firmware file -> the device key that asked
needs map[string][]string // device key -> firmware files not found (may be empty)
probe map[string]int // device key -> the probe's error number
}
var (
fwMissingRE = regexp.MustCompile(`(?:Direct firmware load for|failed to load firmware|firmware: failed to load) ([^ ]+?)(?: failed|[ (]|$)`)
devLineRE = regexp.MustCompile(`^(\S+) (\S+): (.*)$`)
probeRE = regexp.MustCompile(`^probe with driver (\S+) failed with error (-?\d+)`)
probeOldRE = regexp.MustCompile(`^(\S+): probe of (\S+) failed with error (-?\d+)`)
fwNotFoundRE = regexp.MustCompile(`(?i)firmware.*(not found|not available|failed|missing|unable to load|could not load)|(can't|cannot|failed to|unable to) (load|find|request)\b.*firmware`)
)
// parseKernelLog: the lines of `journalctl -k -b` (message only); names maps
// kernel device names to device keys (sysNames).
func parseKernelLog(lines []string, names map[string]string) kernelLog {
k := kernelLog{missing: []string{}, firmware: map[string]string{}, needs: map[string][]string{}, probe: map[string]int{}}
seen := map[string]bool{}
for _, l := range lines {
l = strings.TrimSpace(l)
fw := ""
if m := fwMissingRE.FindStringSubmatch(l); m != nil {
fw = strings.Trim(m[1], ":, ")
if !seen[fw] {
seen[fw] = true
k.missing = append(k.missing, fw)
}
}
if m := probeOldRE.FindStringSubmatch(l); m != nil {
if key := names[m[2]]; key != "" {
k.probe[key], _ = strconv.Atoi(m[3])
}
continue
}
m := devLineRE.FindStringSubmatch(l)
if m == nil {
continue
}
key, msg := names[m[2]], m[3]
if key == "" {
continue
}
switch {
case probeRE.MatchString(msg):
n, _ := strconv.Atoi(probeRE.FindStringSubmatch(msg)[2])
k.probe[key] = n
case fw != "":
k.firmware[fw] = key
if !contains(k.needs[key], fw) {
k.needs[key] = append(k.needs[key], fw)
}
case fwNotFoundRE.MatchString(msg):
if k.needs[key] == nil {
k.needs[key] = []string{}
}
}
}
sort.Strings(k.missing)
for _, f := range k.needs {
sort.Strings(f)
}
return k
}
func contains(l []string, s string) bool {
for _, x := range l {
if x == s {
return true
}
}
return false
}
// sysNames: the kernel's names of PCI and USB devices, and of USB
// interfaces (5-5:1.0), -> the device's key ("pci 1002:4385",
// "usb 0451:3410"), from sysfs (root: "/sys").
func sysNames(root string) map[string]string {
names := map[string]string{}
rd := func(p string) string {
b, _ := os.ReadFile(p)
return strings.TrimPrefix(strings.TrimSpace(string(b)), "0x")
}
for _, d := range mustGlob(filepath.Join(root, "bus/pci/devices/*")) {
if v, p := rd(d+"/vendor"), rd(d+"/device"); v != "" {
names[filepath.Base(d)] = "pci " + v + ":" + p
}
}
usb := filepath.Join(root, "bus/usb/devices")
for _, d := range mustGlob(usb + "/*") {
n := filepath.Base(d)
if dev, _, ok := strings.Cut(n, ":"); ok { // an interface: its device's key
if v := rd(filepath.Join(usb, dev, "idVendor")); v != "" {
names[n] = "usb " + v + ":" + rd(filepath.Join(usb, dev, "idProduct"))
}
} else if v := rd(d + "/idVendor"); v != "" {
names[n] = "usb " + v + ":" + rd(d+"/idProduct")
}
}
return names
}
// loadedModules: the modules in /proc/modules.
func loadedModules(procModules string) map[string]bool {
out := map[string]bool{}
for _, l := range strings.Split(procModules, "\n") {
if f := strings.Fields(l); len(f) > 0 {
out[modName(f[0])] = true
}
}
return out
}
var modprobeDirs = []string{"/etc/modprobe.d", "/run/modprobe.d", "/usr/local/lib/modprobe.d", "/usr/lib/modprobe.d", "/lib/modprobe.d"}
// blacklistedModules: "blacklist X" or "install X /bin/false|true" in the
// modprobe configuration, and module_blacklist= / modprobe.blacklist= on
// the kernel command line.
func blacklistedModules(dirs []string, cmdline string) map[string]bool {
out := map[string]bool{}
for _, dir := range dirs {
for _, f := range mustGlob(filepath.Join(dir, "*.conf")) {
b, _ := os.ReadFile(f)
for _, l := range strings.Split(string(b), "\n") {
w := strings.Fields(l)
switch {
case len(w) >= 2 && w[0] == "blacklist":
out[modName(w[1])] = true
case len(w) >= 3 && w[0] == "install" && (strings.HasSuffix(w[2], "/false") || strings.HasSuffix(w[2], "/true")):
out[modName(w[1])] = true
}
}
}
}
for _, w := range strings.Fields(cmdline) {
for _, p := range []string{"module_blacklist=", "modprobe.blacklist="} {
if v, ok := strings.CutPrefix(w, p); ok {
for _, m := range strings.Split(v, ",") {
if m != "" {
out[modName(m)] = true
}
}
}
}
}
return out
}
// errnoText: what a probe's error number usually means.
var errnoText = map[int]string{
1: "EPERM: operation not permitted", 2: "ENOENT: a file the driver needs is missing (often firmware)",
5: "EIO: input/output error talking to the device", 6: "ENXIO: no such device or address",
12: "ENOMEM: out of memory", 13: "EACCES: permission denied", 16: "EBUSY: the device or a resource is busy (another driver?)",
19: "ENODEV: the driver does not support this device", 22: "EINVAL: invalid argument (unexpected device or setting)",
32: "EPIPE: broken pipe (USB stall)", 61: "ENODATA: no data", 62: "ETIME: timer expired",
71: "EPROTO: protocol error (USB)", 84: "EILSEQ: illegal byte sequence (USB CRC error)",
95: "EOPNOTSUPP: not supported", 110: "ETIMEDOUT: the device did not answer in time",
121: "EREMOTEIO: remote I/O error (I2C/SMBus)", 517: "EPROBE_DEFER: waiting for another driver",
}
func errnoMeaning(n int) string {
if n < 0 {
n = -n
}
if t, ok := errnoText[n]; ok {
return t
}
return "error " + strconv.Itoa(n)
}
// explainHardware adds each driverless device's reason and each missing
// firmware file's device. here: modules this box has (modules.dep);
// loaded, blacklisted: as above.
func explainHardware(res []hwResolved, k kernelLog, here, loaded, blacklisted map[string]bool) {
for i := range res {
r := &res[i]
if r.Kind == "firmware" {
r.Device = k.firmware[r.Key]
continue
}
var onBox []string
for _, m := range r.Modules {
if here[m] || loaded[m] {
onBox = append(onBox, m)
}
}
anyIn := func(set map[string]bool) bool {
for _, m := range onBox {
if set[m] {
return true
}
}
return false
}
errno, failed := k.probe[r.Key]
files, needs := k.needs[r.Key]
switch {
case needs:
r.Reason, r.Firmware = "needs-firmware", files
case failed:
r.Reason = "probe-failed"
case anyIn(loaded):
r.Reason = "loaded-not-bound"
case anyIn(blacklisted):
r.Reason = "blacklisted"
case len(onBox) > 0:
r.Reason = "not-loaded"
}
if failed {
r.Error, r.ErrorText = errno, errnoMeaning(errno)
}
}
}
+128
View File
@@ -0,0 +1,128 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"os"
"path/filepath"
"reflect"
"testing"
)
// A fake sysfs: the Samsung TX-WN's SMBus and TUSB3410,
// a USB interface, an Intel PCI device and a blacklisted sound card.
func fakeSys(t *testing.T) string {
root := t.TempDir()
put := func(dir string, kv map[string]string) {
p := filepath.Join(root, dir)
if err := os.MkdirAll(p, 0o755); err != nil {
t.Fatal(err)
}
for k, v := range kv {
os.WriteFile(filepath.Join(p, k), []byte(v+"\n"), 0o644)
}
}
put("bus/pci/devices/0000:00:14.0", map[string]string{"vendor": "0x1002", "device": "0x4385"})
put("bus/pci/devices/0000:00:14.2", map[string]string{"vendor": "0x1002", "device": "0x4383"})
put("bus/pci/devices/0000:03:00.0", map[string]string{"vendor": "0x8086", "device": "0x4222"})
put("bus/usb/devices/5-5", map[string]string{"idVendor": "0451", "idProduct": "3410"})
put("bus/usb/devices/5-5:1.0", map[string]string{"bInterfaceClass": "ff"})
put("bus/usb/devices/usb5", map[string]string{"idVendor": "1d6b", "idProduct": "0002"})
return root
}
func TestSysNames(t *testing.T) {
got := sysNames(fakeSys(t))
want := map[string]string{"0000:00:14.0": "pci 1002:4385", "0000:00:14.2": "pci 1002:4383", "0000:03:00.0": "pci 8086:4222",
"5-5": "usb 0451:3410", "5-5:1.0": "usb 0451:3410", "usb5": "usb 1d6b:0002"}
if !reflect.DeepEqual(got, want) {
t.Errorf("names %v, want %v", got, want)
}
}
// The TX-WN's kernel log (2026-10-24) and an older kernel's probe line.
var txwnLog = []string{
"usb 5-5: new full-speed USB device number 2 using ohci-pci",
"usb 5-5: Direct firmware load for ti_usb-v0451-p3410.fw failed with error -2",
"usb 5-5: Direct firmware load for ti_3410.fw failed with error -2",
"usb 5-5: ti_download_firmware - firmware not found",
"ti_usb_3410_5052 5-5:1.0: probe with driver ti_usb_3410_5052 failed with error -2",
"snd_hda_intel 0000:00:14.2: Direct firmware load for hda-jack-retask.fw failed with error -2",
"iwl3945: probe of 0000:03:00.0 failed with error -5",
"Direct firmware load for regulatory.db failed with error -2",
"sp5100_tco: SP5100/SB800 TCO WatchDog Timer Driver",
}
func TestParseKernelLog(t *testing.T) {
k := parseKernelLog(txwnLog, sysNames(fakeSys(t)))
if want := []string{"hda-jack-retask.fw", "regulatory.db", "ti_3410.fw", "ti_usb-v0451-p3410.fw"}; !reflect.DeepEqual(k.missing, want) {
t.Errorf("missing %v, want %v", k.missing, want)
}
if k.firmware["ti_3410.fw"] != "usb 0451:3410" || k.firmware["ti_usb-v0451-p3410.fw"] != "usb 0451:3410" ||
k.firmware["hda-jack-retask.fw"] != "pci 1002:4383" || k.firmware["regulatory.db"] != "" {
t.Errorf("firmware -> device %v", k.firmware)
}
if want := []string{"ti_3410.fw", "ti_usb-v0451-p3410.fw"}; !reflect.DeepEqual(k.needs["usb 0451:3410"], want) {
t.Errorf("needs %v", k.needs)
}
if k.probe["usb 0451:3410"] != -2 || k.probe["pci 8086:4222"] != -5 || len(k.probe) != 2 {
t.Errorf("probe %v", k.probe)
}
// A line saying firmware was not found without naming the file.
k = parseKernelLog([]string{"usb 5-5: ti_download_firmware - firmware not found"}, sysNames(fakeSys(t)))
if f, ok := k.needs["usb 0451:3410"]; !ok || len(f) != 0 {
t.Errorf("needs without a file: %v", k.needs)
}
}
func TestBlacklisted(t *testing.T) {
d := t.TempDir()
os.WriteFile(filepath.Join(d, "a.conf"), []byte("# x\nblacklist snd-hda-intel\noptions foo bar=1\ninstall pcspkr /bin/false\ninstall other /sbin/modprobe x\n"), 0o644)
os.WriteFile(filepath.Join(d, "b.txt"), []byte("blacklist ignored\n"), 0o644)
got := blacklistedModules([]string{d, filepath.Join(d, "none")}, "ro quiet module_blacklist=nouveau,radeon modprobe.blacklist=i2c-piix4")
want := map[string]bool{"snd_hda_intel": true, "pcspkr": true, "nouveau": true, "radeon": true, "i2c_piix4": true}
if !reflect.DeepEqual(got, want) {
t.Errorf("blacklisted %v, want %v", got, want)
}
if l := loadedModules("i2c_piix4 28672 0 - Live 0x0\nsp5100_tco 20480 0 - Live 0x0\n"); !l["i2c_piix4"] || !l["sp5100_tco"] || len(l) != 2 {
t.Errorf("loaded %v", l)
}
}
// Each reason, on the TX-WN's devices and three made-up ones.
func TestExplainHardware(t *testing.T) {
res := []hwResolved{
{Kind: "device", Key: "pci 1002:4385", Modules: []string{"i2c_piix4", "sp5100_tco"}, Verdict: "driver-here"},
{Kind: "device", Key: "usb 0451:3410", Modules: []string{"ti_usb_3410_5052"}, Verdict: "driver-here"},
{Kind: "device", Key: "pci 8086:4222", Modules: []string{"iwl3945"}, Verdict: "driver-here"},
{Kind: "device", Key: "pci 1002:4383", Modules: []string{"snd_hda_intel"}, Verdict: "driver-here"},
{Kind: "device", Key: "pci 10ec:8168", Modules: []string{"r8169"}, Verdict: "driver-here"},
{Kind: "device", Key: "usb a69c:5721", Verdict: "not-in-cantabile"},
{Kind: "device", Key: "pci 8086:0be1", Modules: []string{"gma500_gfx"}, Verdict: "other-edition"},
{Kind: "firmware", Key: "ti_3410.fw", Verdict: "not-in-cantabile"},
{Kind: "firmware", Key: "regulatory.db", Verdict: "here"},
}
k := parseKernelLog(txwnLog[:5], sysNames(fakeSys(t)))
k.probe["pci 8086:4222"] = -5
here := map[string]bool{"i2c_piix4": true, "sp5100_tco": true, "ti_usb_3410_5052": true, "iwl3945": true, "snd_hda_intel": true, "r8169": true}
loaded := map[string]bool{"i2c_piix4": true, "sp5100_tco": true, "ti_usb_3410_5052": true}
black := map[string]bool{"snd_hda_intel": true}
explainHardware(res, k, here, loaded, black)
want := map[string]string{"pci 1002:4385": "loaded-not-bound", "usb 0451:3410": "needs-firmware", "pci 8086:4222": "probe-failed",
"pci 1002:4383": "blacklisted", "pci 10ec:8168": "not-loaded", "usb a69c:5721": "", "pci 8086:0be1": ""}
for _, r := range res {
if r.Kind == "device" && r.Reason != want[r.Key] {
t.Errorf("%s: reason %q, want %q", r.Key, r.Reason, want[r.Key])
}
}
ti := res[1]
if ti.Error != -2 || ti.ErrorText == "" || !reflect.DeepEqual(ti.Firmware, []string{"ti_3410.fw", "ti_usb-v0451-p3410.fw"}) {
t.Errorf("TUSB3410: %+v", ti)
}
if res[2].Error != -5 || res[2].ErrorText != errnoMeaning(5) {
t.Errorf("probe-failed: %+v", res[2])
}
if res[7].Device != "usb 0451:3410" || res[8].Device != "" {
t.Errorf("firmware devices: %q %q", res[7].Device, res[8].Device)
}
}
+179
View File
@@ -0,0 +1,179 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
// Missing drivers and firmware, resolved on the box (docs/hardware-support.md,
// step 3). Every Cantabile image carries a small hardware database made from the
// full kernel and firmware packages before an edition removes anything
// (/usr/lib/cantabile/hwdb, mkosi.postinst.chroot): the kernel's modules.alias and
// the list of firmware files. With it the box tells, for each device without
// a driver and each firmware file the kernel did not find, which case it is:
//
// device: driver-here a module of this Cantabile matches (blacklisted, or
// its probe failed)
// other-edition Cantabile's kernel has a module, this edition not
// not-in-cantabile no module in Cantabile's kernel (a driver pack with
// an out-of-tree driver, or a device it can't use)
// firmware: here the file is on this box (the load failed for
// another reason, e.g. too early at boot)
// other-edition in Cantabile's packages, removed in this edition
// not-in-cantabile not in Cantabile's packages (a firmware pack)
//
// And why a device has no driver on this box (the box
// knows best), from its modules, the modprobe
// configuration and the kernel log (hwreason.go): reason not-loaded,
// blacklisted, loaded-not-bound, probe-failed (with the error) or
// needs-firmware (with the files); a missing firmware file carries the
// device that asked for it.
import (
"bufio"
"compress/gzip"
"os"
"path"
"path/filepath"
"sort"
"strings"
)
var hwdbDir = "/usr/lib/cantabile/hwdb"
type hwDev struct {
Bus, ID string
Modalias []string
}
type hwResolved struct {
Kind string `json:"kind"` // device | firmware
Key string `json:"key"` // "pci 8086:0be1" | firmware path
Modules []string `json:"modules,omitempty"`
Verdict string `json:"verdict"`
Modalias []string `json:"modalias,omitempty"`
// Why a device has no driver (hwreason.go); for a
// firmware file, the device that asked for it ("usb 0451:3410").
Reason string `json:"reason,omitempty"`
Error int `json:"error,omitempty"` // the probe's error number (-2)
ErrorText string `json:"error_text,omitempty"` // and what it means
Firmware []string `json:"firmware,omitempty"` // needs-firmware: the files the log names
Device string `json:"device,omitempty"`
}
// gzLines: the lines of a gzipped text file (nil if it can't be read).
func gzLines(p string) []string {
f, err := os.Open(p)
if err != nil {
return nil
}
defer f.Close()
z, err := gzip.NewReader(f)
if err != nil {
return nil
}
var out []string
sc := bufio.NewScanner(z)
sc.Buffer(make([]byte, 64*1024), 1024*1024)
for sc.Scan() {
out = append(out, sc.Text())
}
return out
}
func modName(s string) string { return strings.ReplaceAll(s, "-", "_") }
// modulesHere: the modules this box's kernel tree has (modules.dep).
func modulesHere(root string) map[string]bool {
here := map[string]bool{}
b, err := os.ReadFile(filepath.Join(root, "modules.dep"))
if err != nil {
return here
}
for _, l := range strings.Split(string(b), "\n") {
f, _, ok := strings.Cut(l, ":")
if !ok {
continue
}
n := filepath.Base(f)
if i := strings.Index(n, ".ko"); i > 0 {
here[modName(n[:i])] = true
}
}
return here
}
// fwName: a firmware path without the compression the kernel adds itself.
func fwName(s string) string {
for _, x := range []string{".zst", ".xz"} {
s = strings.TrimSuffix(s, x)
}
return s
}
func resolveHardware(devs []hwDev, missingFirmware []string, kernelRoot, firmwareRoot string) []hwResolved {
out := []hwResolved{}
if len(devs) == 0 && len(missingFirmware) == 0 {
return out
}
type alias struct{ pattern, module string }
var aliases []alias
for _, l := range gzLines(filepath.Join(hwdbDir, "modules.alias.gz")) {
f := strings.Fields(l)
if len(f) == 3 && f[0] == "alias" {
aliases = append(aliases, alias{f[1], modName(f[2])})
}
}
here := modulesHere(kernelRoot)
for _, d := range devs {
mods := map[string]bool{}
for _, ma := range d.Modalias {
for _, a := range aliases {
if ok, _ := path.Match(a.pattern, ma); ok {
mods[a.module] = true
}
}
}
r := hwResolved{Kind: "device", Key: d.Bus + " " + d.ID, Modalias: d.Modalias}
for m := range mods {
r.Modules = append(r.Modules, m)
}
sort.Strings(r.Modules)
switch {
case len(aliases) == 0:
r.Verdict = "unknown" // no database (an image from before it)
case len(r.Modules) == 0:
r.Verdict = "not-in-cantabile"
default:
r.Verdict = "other-edition"
for _, m := range r.Modules {
if here[m] {
r.Verdict = "driver-here"
}
}
}
out = append(out, r)
}
known := map[string]bool{}
for _, l := range gzLines(filepath.Join(hwdbDir, "firmware.txt.gz")) {
known[fwName(l)] = true
}
for _, fw := range missingFirmware {
r := hwResolved{Kind: "firmware", Key: fw}
onBox := false
for _, x := range []string{"", ".zst", ".xz"} {
if _, err := os.Stat(filepath.Join(firmwareRoot, fw+x)); err == nil {
onBox = true
}
}
switch {
case len(known) == 0:
r.Verdict = "unknown"
case onBox:
r.Verdict = "here"
case known[fwName(fw)]:
r.Verdict = "other-edition"
default:
r.Verdict = "not-in-cantabile"
}
out = append(out, r)
}
return out
}
+56
View File
@@ -0,0 +1,56 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"compress/gzip"
"os"
"path/filepath"
"testing"
)
func writeGz(t *testing.T, p string, lines string) {
f, err := os.Create(p)
if err != nil {
t.Fatal(err)
}
z := gzip.NewWriter(f)
z.Write([]byte(lines))
z.Close()
f.Close()
}
// The box resolves each missing driver and firmware into its case.
func TestResolveHardware(t *testing.T) {
d := t.TempDir()
hwdbDir = filepath.Join(d, "hwdb")
os.MkdirAll(hwdbDir, 0o755)
writeGz(t, filepath.Join(hwdbDir, "modules.alias.gz"),
"alias pci:v00008086d00004222sv*sd*bc*sc*i* iwl3945\n"+
"alias usb:v0BDAp8813d*dc*dsc*dp*ic*isc*ip*in* rtw88_8814au\n")
writeGz(t, filepath.Join(hwdbDir, "firmware.txt.gz"), "iwlwifi-3945-2.ucode\nrtw88/rtw8814a_fw.bin.zst\n")
kroot := filepath.Join(d, "modules")
os.MkdirAll(kroot, 0o755)
os.WriteFile(filepath.Join(kroot, "modules.dep"), []byte("kernel/drivers/net/wireless/realtek/rtw88/rtw88_8814au.ko.xz: x\n"), 0o644)
fwroot := filepath.Join(d, "firmware")
os.MkdirAll(filepath.Join(fwroot, "rtw88"), 0o755)
os.WriteFile(filepath.Join(fwroot, "rtw88", "rtw8814a_fw.bin.zst"), nil, 0o644)
got := resolveHardware([]hwDev{
{"pci", "8086:4222", []string{"pci:v00008086d00004222sv00008086sd00001005bc02sc80i00"}},
{"usb", "0bda:8813", []string{"usb:v0BDAp8813d0000dc00dsc00dp00icFFiscFFipFFin00"}},
{"usb", "a69c:5721", []string{"usb:vA69Cp5721d0100dc00dsc00dp00icFFiscFFipFFin00"}},
}, []string{"iwlwifi-3945-2.ucode", "rtw88/rtw8814a_fw.bin", "aic8800/fw.bin"}, kroot, fwroot)
want := map[string]string{
"pci 8086:4222": "other-edition", "usb 0bda:8813": "driver-here", "usb a69c:5721": "not-in-cantabile",
"iwlwifi-3945-2.ucode": "other-edition", "rtw88/rtw8814a_fw.bin": "here", "aic8800/fw.bin": "not-in-cantabile",
}
if len(got) != len(want) {
t.Fatalf("got %d results, want %d: %+v", len(got), len(want), got)
}
for _, r := range got {
if want[r.Key] != r.Verdict {
t.Errorf("%s: %s, want %s", r.Key, r.Verdict, want[r.Key])
}
}
}
+235
View File
@@ -0,0 +1,235 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
// The agent's local socket: one JSON object per line, one agent at a time
// (a new connection replaces the old one). The site's key stays here.
//
// agent -> link {"op":"hello"} -> {"op":"hello","site":"<id>"}
// agent -> link {"op":"tel","id":7,"msg_id":"<site>:<seq>","data":{...}}
// -> {"op":"ack","id":7,"ok":true}
// (ok only once JetStream stored the batch)
// agent -> link {"op":"status"|"event","data":{...}} (published, no answer)
// agent -> link {"op":"plan"|"action","data":{...}} (published, no answer;
// plans at most every 5 min, actions at most 120 an hour)
// agent -> link {"op":"inventory","data":{...}} (the devices' specs; published at most every 10 min)
// agent -> link {"op":"state"} -> {"op":"state","ok":<NATS connected>}
// link -> agent {"op":"command","id":"<cmd id>","cmd":"...","args":{...}}
// agent -> link {"op":"result","id":"<cmd id>","ok":true,"message":"..."}
import (
"bufio"
"encoding/json"
"errors"
"log/slog"
"net"
"os"
"path/filepath"
"strconv"
"sync"
"time"
)
type local struct {
l *link
ln net.Listener
mu sync.Mutex
conn net.Conn
wmu sync.Mutex
// results the link waits for, by command id
waits map[string]chan msg
// rate limits on what the agent publishes (allow)
rmu sync.Mutex
lastPlan time.Time
lastInv time.Time
actions []time.Time
}
// Limits on the agent's own messages: a plan at most every 5 minutes (it
// is re-made every 15), actions at most 120 an hour (a broken agent must
// not flood the platform).
const (
planEvery = 5 * time.Minute
inventoryEvery = 10 * time.Minute
actionsPerHour = 120
)
// allow: whether this plan or action may go out now (and counts it).
func (lc *local) allow(op string, now time.Time) bool {
lc.rmu.Lock()
defer lc.rmu.Unlock()
if op == "plan" {
if now.Sub(lc.lastPlan) < planEvery {
return false
}
lc.lastPlan = now
return true
}
if op == "inventory" {
if !lc.lastInv.IsZero() && now.Sub(lc.lastInv) < inventoryEvery {
return false
}
lc.lastInv = now
return true
}
keep := lc.actions[:0]
for _, t := range lc.actions {
if now.Sub(t) < time.Hour {
keep = append(keep, t)
}
}
lc.actions = keep
if len(lc.actions) >= actionsPerHour {
return false
}
lc.actions = append(lc.actions, now)
return true
}
type msg struct {
Op string `json:"op"`
ID json.RawMessage `json:"id,omitempty"`
MsgID string `json:"msg_id,omitempty"`
Data json.RawMessage `json:"data,omitempty"`
Site string `json:"site,omitempty"`
OK *bool `json:"ok,omitempty"`
Error string `json:"error,omitempty"`
Message string `json:"message,omitempty"`
Cmd string `json:"cmd,omitempty"`
Args map[string]string `json:"args,omitempty"`
}
func listen(l *link, path string) (*local, error) {
os.MkdirAll(filepath.Dir(path), 0o755)
os.Remove(path)
ln, err := net.Listen("unix", path)
if err != nil {
return nil, err
}
// The agent runs as the same user (one container) or its group; on the
// Hub the link is on the box and the agent in its container: the socket
// is that user's (CANTABILE_LINK_SOCKET_OWNER, a uid).
os.Chmod(path, 0o660)
if uid, err := strconv.Atoi(os.Getenv("CANTABILE_LINK_SOCKET_OWNER")); err == nil && uid > 0 {
os.Chown(path, uid, uid)
os.Chown(filepath.Dir(path), uid, uid)
os.Chmod(filepath.Dir(path), 0o700)
}
lc := &local{l: l, ln: ln, waits: map[string]chan msg{}}
go lc.accept()
return lc, nil
}
func (lc *local) close() { lc.ln.Close() }
func (lc *local) connected() bool {
lc.mu.Lock()
defer lc.mu.Unlock()
return lc.conn != nil
}
func (lc *local) accept() {
for {
c, err := lc.ln.Accept()
if err != nil {
return
}
lc.mu.Lock()
if lc.conn != nil {
lc.conn.Close()
}
lc.conn = c
lc.mu.Unlock()
slog.Info("agent connected")
go lc.serve(c)
}
}
func (lc *local) send(c net.Conn, m msg) error {
b, _ := json.Marshal(m)
lc.wmu.Lock()
defer lc.wmu.Unlock()
c.SetWriteDeadline(time.Now().Add(10 * time.Second))
_, err := c.Write(append(b, '\n'))
return err
}
func (lc *local) serve(c net.Conn) {
defer func() {
lc.mu.Lock()
if lc.conn == c {
lc.conn = nil
}
lc.mu.Unlock()
c.Close()
slog.Info("agent disconnected")
}()
sc := bufio.NewScanner(c)
sc.Buffer(make([]byte, 64<<10), 1<<20) // a telemetry batch: at most 1 MiB
for sc.Scan() {
var m msg
if json.Unmarshal(sc.Bytes(), &m) != nil {
continue
}
switch m.Op {
case "hello":
lc.send(c, msg{Op: "hello", Site: lc.l.id})
case "tel":
ok := true
ans := msg{Op: "ack", ID: m.ID, OK: &ok}
if m.MsgID == "" || len(m.Data) == 0 {
ok, ans.Error = false, "msg_id and data needed"
} else if err := lc.l.telemetry(m.Data, m.MsgID); err != nil {
ok, ans.Error = false, err.Error()
}
lc.send(c, ans)
case "state":
nc, _ := lc.l.conn()
up := nc != nil && nc.IsConnected()
lc.send(c, msg{Op: "state", OK: &up})
case "status", "event":
if len(m.Data) > 0 {
lc.l.publish(m.Op, m.Data)
}
case "plan", "action", "inventory":
if len(m.Data) > 0 && lc.allow(m.Op, time.Now()) {
lc.l.publish(m.Op, m.Data)
}
case "result":
var id string
json.Unmarshal(m.ID, &id)
lc.mu.Lock()
w := lc.waits[id]
lc.mu.Unlock()
if w != nil {
select {
case w <- m:
default:
}
}
}
}
}
// command: a checked command to the agent, and its answer (or why none).
func (lc *local) command(c command, timeout time.Duration) (bool, string) {
lc.mu.Lock()
conn := lc.conn
w := make(chan msg, 1)
lc.waits[c.ID] = w
lc.mu.Unlock()
defer func() { lc.mu.Lock(); delete(lc.waits, c.ID); lc.mu.Unlock() }()
if conn == nil {
return false, "the agent is not running"
}
id, _ := json.Marshal(c.ID)
if err := lc.send(conn, msg{Op: "command", ID: id, Cmd: c.Cmd, Args: c.Args}); err != nil {
return false, "the agent did not take it: " + err.Error()
}
select {
case r := <-w:
return r.OK != nil && *r.OK, r.Message
case <-time.After(timeout):
return false, errors.New("no answer from the agent").Error()
}
}
+959
View File
@@ -0,0 +1,959 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
// cantabile-link: the site's side of the device API, beside the Edge Agent.
// It enrols the site by
// itself (proof of work), keeps one NATS connection to the platform
// (WebSocket over TLS), reports a heartbeat every minute, carries out the
// platform's commands after checking their signature (the command key) and
// passes them to the agent, and publishes the agent's telemetry to
// JetStream. The site's key never leaves this process: the agent talks to
// it over a local socket (local.go).
//
// State: CANTABILE_LINK_STATE (default /data/link, root or the agent's user
// only): the key (seed), the current credentials, the commands done.
// Configuration only from the environment.
package main
import (
"bytes"
"context"
"crypto"
"crypto/ecdsa"
"crypto/rsa"
"crypto/sha256"
"crypto/x509"
"encoding/base64"
"encoding/hex"
"encoding/json"
"encoding/pem"
"errors"
"fmt"
"io"
"log/slog"
"math/bits"
"math/rand"
"net/http"
"net/url"
"os"
"os/signal"
"path/filepath"
"regexp"
"runtime"
"sort"
"strings"
"sync"
"sync/atomic"
"syscall"
"time"
"github.com/nats-io/nats.go"
"github.com/nats-io/nkeys"
"golang.org/x/crypto/scrypt"
)
const hbEvery = time.Minute
var version = "0.0.0-dev" // set at build time (-ldflags -X main.version=...); fleet wants x.y.z[-suffix]
type config struct {
URL string // CANTABILE_DEVICES_URL, e.g. https://devices.cantabile.cloud
State string // CANTABILE_LINK_STATE
CertFile string // CANTABILE_COMMAND_CERT: the certificate of the command key
Socket string // CANTABILE_LINK_SOCKET: the agent's local socket
HAUUID string // CANTABILE_HA_UUID_FILE: Home Assistant's instance id (site id)
SiteID string // CANTABILE_SITE_ID: tests only, instead of the id from HA
Prefix string // CANTABILE_SUBJECT_PREFIX, default ctb (ctb.site.<id>.<kind>, ctb.cmd.<id>)
Claim string // CANTABILE_CLAIM_FILE: the owner's claim code (the Hub's setup wizard and panel write it)
// Data bundles for the agent (bundles.go): the bundle key's certificate,
// and the agent's state directory the bundles are written into.
BundleCert string // CANTABILE_BUNDLE_CERT
AgentState string // CANTABILE_AGENT_STATE
// Direct paths (endpoints.go, docs/direct-link.md), tried before URL:
// DNS-only names whose TLS ends in Cantabile's cluster, pinned to the
// devices CA and/or SPKI pins. Empty (the default): only URL, as before.
Direct []string // CANTABILE_DEVICES_DIRECT, e.g. https://devices.cantabile.cloud
DirectCA string // CANTABILE_DEVICES_CA: the devices CA(s), PEM (current and next)
DirectSPKI []string // CANTABILE_DEVICES_SPKI: base64 SHA-256 of SubjectPublicKeyInfo
}
func env(k, def string) string {
if v := os.Getenv(k); v != "" {
return v
}
return def
}
func loadConfig() config {
return config{
URL: strings.TrimRight(env("CANTABILE_DEVICES_URL", "https://devices.cantabile.cloud"), "/"),
State: env("CANTABILE_LINK_STATE", "/data/link"),
CertFile: env("CANTABILE_COMMAND_CERT", "/etc/cantabile/commands.pem"),
Socket: env("CANTABILE_LINK_SOCKET", "/run/cantabile/link.sock"),
HAUUID: env("CANTABILE_HA_UUID_FILE", "/config/.storage/core.uuid"),
SiteID: os.Getenv("CANTABILE_SITE_ID"),
Prefix: env("CANTABILE_SUBJECT_PREFIX", "ctb"),
Claim: env("CANTABILE_CLAIM_FILE", "/data/claim-code"),
// The Hub: the box's keys in the slot, the agent's /data in
// /data/cantabile/edge; a container site: both in its /data.
BundleCert: env("CANTABILE_BUNDLE_CERT", map[bool]string{true: "/etc/cantabile/keys/bundles.pem", false: "/data/bundles.pem"}[isHub()]),
AgentState: env("CANTABILE_AGENT_STATE", map[bool]string{true: "/data/cantabile/edge/state", false: "/data/state"}[isHub()]),
Direct: splitList(os.Getenv("CANTABILE_DEVICES_DIRECT")),
DirectCA: env("CANTABILE_DEVICES_CA", map[bool]string{true: "/etc/cantabile/keys/devices-ca.pem", false: "/data/devices-ca.pem"}[isHub()]),
DirectSPKI: splitList(os.Getenv("CANTABILE_DEVICES_SPKI")),
}
}
type link struct {
cfg config
eps []*endpoint // the paths in order (endpoints.go)
cur atomic.Pointer[endpoint] // the current session's
id string
kp nkeys.KeyPair
cert crypto.PublicKey
mu sync.Mutex
jwt string
ncMu sync.Mutex
nc *nats.Conn
js nats.JetStreamContext
loc *local
// renewed since this start; the last session got connected.
renewed, connected bool
doneMu sync.Mutex
started time.Time
// The Hub's reports (hub.go): CPU sample, last hardware report, event log offset.
cpu cpuSample
hwHash string
hwAt time.Time
evOff int64
// The claim code the last renew carried (a new one: renew again).
sentClaim string
}
func main() {
slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, nil)))
if err := run(); err != nil {
slog.Error("exit", "error", err)
os.Exit(1)
}
}
func run() error {
if len(os.Args) == 3 && os.Args[1] == "sign" { // the logs tool: a support request (hub.go)
return signCmd(loadConfig(), os.Args[2])
}
if len(os.Args) == 2 && os.Args[1] == "hwids" { // the status splash (the raw ids, on the box only)
for _, x := range rawIDs() {
fmt.Printf("%s: %s\n", x[0], x[1])
}
return nil
}
if len(os.Args) == 2 && os.Args[1] == "fingerprint" { // the HA add-on's start, as root (fingerprint.go)
os.Unsetenv("CANTABILE_FINGERPRINT_FILE")
return json.NewEncoder(os.Stdout).Encode(fingerprint())
}
l := &link{cfg: loadConfig(), started: time.Now()}
var err error
if l.id, err = siteID(l.cfg); err != nil {
return err
}
if err := os.MkdirAll(l.cfg.State, 0o700); err != nil {
return err
}
if l.kp, err = loadKey(l.cfg.State); err != nil {
return err
}
if l.cert, err = commandKey(l.cfg.CertFile); err != nil {
return err
}
os.WriteFile(filepath.Join(l.cfg.State, "site-id"), []byte(l.id+"\n"), 0o644)
if isHub() { // the agent's container sees the socket's directory, not the link's state
os.MkdirAll(filepath.Dir(l.cfg.Socket), 0o755)
os.WriteFile(filepath.Join(filepath.Dir(l.cfg.Socket), "site-id"), []byte(l.id+"\n"), 0o644)
}
l.eps = endpoints(l.cfg)
paths := make([]string, len(l.eps))
for i, e := range l.eps {
paths[i] = e.URL + " (" + e.Kind + ")"
}
slog.Info("starting", "site", l.id, "paths", paths, "version", version)
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
defer stop()
if l.loc, err = listen(l, l.cfg.Socket); err != nil {
return err
}
defer l.loc.close()
if isHub() { // the owner's End now in the panel: support's sessions close
usr1 := make(chan os.Signal, 1)
signal.Notify(usr1, syscall.SIGUSR1)
go func() {
for range usr1 {
l.closeAll()
}
}()
writeTermState()
writePanelState()
}
go l.loop(ctx)
<-ctx.Done()
if nc, _ := l.conn(); nc != nil {
nc.Drain()
}
return nil
}
func (l *link) conn() (*nats.Conn, nats.JetStreamContext) {
l.ncMu.Lock()
defer l.ncMu.Unlock()
return l.nc, l.js
}
func (l *link) setConn(nc *nats.Conn, js nats.JetStreamContext) {
l.ncMu.Lock()
l.nc, l.js = nc, js
l.ncMu.Unlock()
}
// ---- identity
var siteIDRE = regexp.MustCompile(`^[0-9a-f]{32}$`)
// hubSiteIDFile: a Hub's site id, from its hardware (written once by
// /usr/lib/cantabile/serial with the box's serial, before the link starts).
var hubSiteIDFile = "/data/cantabile/edge/site-id"
// siteID: on a Hub from the box's hardware (HA is an
// add-on installed after setup, so the link must start without it, and
// support must reach a box whose setup failed); elsewhere from Home
// Assistant's instance id (the same as long as HA's configuration lives; a
// new HA is a new site, recovered through the owner's account).
// Never HA's raw id.
func siteID(cfg config) (string, error) {
// The site this box was merged into (a reinstall recognised by fleet,
// reinstall.go): its earlier site's id from now on.
if id := strings.TrimSpace(read(filepath.Join(cfg.State, adoptedFile))); siteIDRE.MatchString(id) && cfg.SiteID == "" {
return id, nil
}
if cfg.SiteID != "" {
if !siteIDRE.MatchString(cfg.SiteID) {
return "", errors.New("CANTABILE_SITE_ID: 32 lowercase hex characters")
}
return cfg.SiteID, nil
}
if isHub() {
if id := strings.TrimSpace(read(hubSiteIDFile)); siteIDRE.MatchString(id) {
return id, nil
}
return "", errors.New("site id: " + hubSiteIDFile + " missing (cantabile-serial.service writes it)")
}
b, err := os.ReadFile(cfg.HAUUID)
if err != nil {
return "", fmt.Errorf("site id: Home Assistant's instance id: %w", err)
}
var u struct {
Data struct {
UUID string `json:"uuid"`
} `json:"data"`
}
if json.Unmarshal(b, &u) != nil || len(u.Data.UUID) < 16 {
return "", errors.New("site id: no uuid in " + cfg.HAUUID)
}
sum := sha256.Sum256([]byte("cantabile-site-id:" + strings.ToLower(u.Data.UUID)))
return hex.EncodeToString(sum[:16]), nil
}
// enrolProof: from ids only root can read on the host (DMI
// product UUID and serials); "" in a container that cannot read them (no
// proof: a new key for a known site then needs the fleet manager
// until the claim code comes).
func enrolProof() string {
var parts []string
for _, f := range []string{"product_uuid", "product_serial", "board_serial"} {
b, err := os.ReadFile("/sys/class/dmi/id/" + f)
if err != nil {
continue
}
if v := strings.TrimSpace(string(b)); !placeholder(v) {
parts = append(parts, f+"="+v)
}
}
if len(parts) == 0 {
return ""
}
sum := sha256.Sum256([]byte("cantabile-site-enrol:" + strings.Join(parts, ",")))
return hex.EncodeToString(sum[:])
}
// placeholder: a DMI value boards ship when nobody filled it in.
func placeholder(v string) bool {
l := strings.ToLower(v)
if len(l) < 4 || strings.Trim(l, l[:1]) == "" || strings.Trim(l, "0-") == "" || strings.Trim(l, "f-") == "" {
return true
}
for _, p := range []string{"to be filled", "default string", "system serial", "serial number", "not specified",
"not applicable", "none", "n/a", "0123456789", "123456789", "chassis serial", "base board serial", "oem"} {
if strings.Contains(l, p) {
return true
}
}
return false
}
// loadKey: this installation's NATS user key (new after a reinstall).
func loadKey(dir string) (nkeys.KeyPair, error) {
p := filepath.Join(dir, "seed")
if b, err := os.ReadFile(p); err == nil {
return nkeys.FromSeed(bytes.TrimSpace(b))
}
kp, err := nkeys.CreateUser()
if err != nil {
return nil, err
}
seed, _ := kp.Seed()
return kp, os.WriteFile(p, seed, 0o600)
}
// commandKey: the key the platform signs commands with (its own: bundles
// have another).
func commandKey(path string) (crypto.PublicKey, error) {
b, err := os.ReadFile(path)
if err != nil {
return nil, err
}
blk, _ := pem.Decode(b)
if blk == nil {
return nil, errors.New(path + ": not PEM")
}
c, err := x509.ParseCertificate(blk.Bytes)
if err != nil {
return nil, err
}
return c.PublicKey, nil
}
// withPort gives a ws/wss URL without a port its default one: nats.go
// would append it after the path ("/nats:443") and dial port 0.
func withPort(s string) string {
u, err := url.Parse(s)
if err != nil || u.Port() != "" || u.Host == "" {
return s
}
switch u.Scheme {
case "wss":
u.Host += ":443"
case "ws":
u.Host += ":80"
default:
return s
}
return u.String()
}
// ---- enrolment and credentials
type creds struct {
Box string `json:"box"` // the fleet's name for the site id
JWT string `json:"jwt"`
NATS string `json:"nats"`
RenewAfter int64 `json:"renew_after"`
At int64 `json:"at"`
}
func (l *link) saveCreds(c creds) {
c.At = time.Now().Unix()
b, _ := json.Marshal(c)
os.WriteFile(filepath.Join(l.cfg.State, "creds.json"), b, 0o600)
l.mu.Lock()
l.jwt = c.JWT
l.mu.Unlock()
}
func (l *link) loadCreds() (creds, bool) {
var c creds
b, err := os.ReadFile(filepath.Join(l.cfg.State, "creds.json"))
if err != nil || json.Unmarshal(b, &c) != nil || c.Box != l.id || c.JWT == "" {
return c, false
}
l.mu.Lock()
l.jwt = c.JWT
l.mu.Unlock()
return c, true
}
var errRevoked = errors.New("revoked")
// errClaim: the platform wants a (valid) claim code; the link waits until
// the owner enters another (claimWait).
var errClaim = errors.New("claim code")
// claim: the owner's claim code, "" if none yet.
func (l *link) claim() string {
b, _ := os.ReadFile(l.cfg.Claim)
return strings.TrimSpace(string(b))
}
// enrolState: why the site is not enrolled ("" once it is), for the box's
// panel (<state>/enrol-refused).
func (l *link) enrolState(msg string) {
p := filepath.Join(l.cfg.State, "enrol-refused")
if msg == "" {
os.Remove(p)
return
}
os.WriteFile(p, []byte(msg+"\n"), 0o644)
}
// claimWait: until the claim code changes (checked every 10 s), at most
// six hours.
func (l *link) claimWait(ctx context.Context) {
was := l.claim()
for end := time.Now().Add(6 * time.Hour); time.Now().Before(end); {
select {
case <-ctx.Done():
return
case <-time.After(10 * time.Second):
}
if l.claim() != was {
return
}
}
}
var httpc = &http.Client{Timeout: 60 * time.Second}
func (l *link) post(path string, hdr map[string]string, body any, out any) (int, error) {
b, _ := json.Marshal(body)
req, _ := http.NewRequest("POST", l.base()+path, bytes.NewReader(b))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("User-Agent", "cantabile-link/"+version)
for k, v := range hdr {
req.Header.Set(k, v)
}
resp, err := l.client().Do(req)
if err != nil {
return 0, pathError{err}
}
defer resp.Body.Close()
data, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
if resp.StatusCode == 200 && out != nil {
return 200, json.Unmarshal(data, out)
}
err = fmt.Errorf("HTTP %d: %s", resp.StatusCode, bytes.TrimSpace(data))
if proxyDown(resp.StatusCode) {
err = pathError{err}
}
return resp.StatusCode, err
}
type challenge struct {
Challenge string `json:"challenge"`
Bits int `json:"bits"`
Scrypt struct {
N, R, P, Len int
Salt string
} `json:"scrypt"`
}
// solve: the proof of work for a challenge (the fleet's pow.go).
func solve(ch challenge) int {
for nonce := 0; ; nonce++ {
k, _ := scrypt.Key([]byte(fmt.Sprintf("%s:%d", ch.Challenge, nonce)), []byte(ch.Scrypt.Salt), ch.Scrypt.N, ch.Scrypt.R, ch.Scrypt.P, ch.Scrypt.Len)
if zeroBits(k) >= ch.Bits {
return nonce
}
}
}
// proxyDown: a proxy on the path answered, the platform behind it did not.
func proxyDown(code int) bool { return code == 502 || code == 503 || code == 504 }
func (l *link) enrol() error {
req, _ := http.NewRequest("GET", l.base()+"/api/devices/challenge", nil)
req.Header.Set("User-Agent", "cantabile-link/"+version)
resp, err := l.client().Do(req)
if err != nil {
return pathError{err}
}
if proxyDown(resp.StatusCode) {
resp.Body.Close()
return pathError{fmt.Errorf("challenge: HTTP %d", resp.StatusCode)}
}
var ch challenge
err = json.NewDecoder(io.LimitReader(resp.Body, 8192)).Decode(&ch)
resp.Body.Close()
if err != nil || ch.Challenge == "" || ch.Scrypt.N == 0 {
return fmt.Errorf("challenge: %v", err)
}
nonce := solve(ch)
pub, _ := l.kp.PublicKey()
var c creds
code, err := l.post("/api/devices/enrol", map[string]string{"X-Fig-Proof": fmt.Sprintf("%s %d", ch.Challenge, nonce)},
map[string]any{"id": l.id, "nkey": pub, "version": enrolVersion(), "arch": runtime.GOARCH, "model": enrolModel(),
"info": map[string]any{"kind": map[bool]string{true: "hub", false: "ha-addon"}[isHub()]}, "proof": enrolProof(), "claim": l.claim(),
"serial": boxSerial(), "test": testFleet().Test, "fingerprint": fingerprint()}, &c)
if code == 403 && err != nil && strings.Contains(err.Error(), "revoked") {
return errRevoked
}
if code == 403 && err != nil && strings.Contains(err.Error(), "claim code") {
msg := "claim code not valid"
if strings.Contains(err.Error(), "another box") { // fleet reinstall.go: the code is another site's
msg = "claim code belongs to another box"
} else if strings.Contains(err.Error(), "required") {
msg = "claim code required"
}
l.enrolState(msg)
return fmt.Errorf("%w: %s", errClaim, msg)
}
if err != nil {
if isPathError(err) {
return pathError{fmt.Errorf("enrol: %w", err)}
}
return fmt.Errorf("enrol: %w", err)
}
if c.Box != "" && c.Box != l.id { // fleet merged this reinstall into the earlier site (reinstall.go)
return l.adopt(c.Box, c)
}
l.saveCreds(c)
l.sentClaim = l.claim()
l.enrolState("")
slog.Info("enrolled", "site", l.id)
return nil
}
// renew: fresh credentials, signed with this installation's key.
func (l *link) renew() error {
ts := time.Now().Unix()
text := fmt.Sprintf("renew:%s:%d", l.id, ts)
body := map[string]any{"id": l.id, "ts": ts}
if p := enrolProof(); p != "" {
text += ":" + p
body["proof"] = p
}
// A claim code entered after the site enrolled (the box enrolled before
// the owner reached that step): signed too, and the
// platform ties it to the site if the site has none.
claim := l.claim()
if claim != "" {
text += ":claim:" + claim
body["claim"] = claim
}
sig, _ := l.kp.Sign([]byte(text))
body["sig"] = base64.StdEncoding.EncodeToString(sig)
var c creds
code, err := l.post("/api/devices/renew", nil, body, &c)
switch {
case code == 404:
return l.enrol()
case code == 403 && err != nil && strings.Contains(err.Error(), "revoked"):
return errRevoked
case code == 403 && err != nil && strings.Contains(err.Error(), "bad signature"):
slog.Warn("renew: the platform has another key for this site; enrolling again")
return l.enrol()
case err != nil:
return err
}
if c.Box != "" && c.Box != l.id { // merged into the earlier site meanwhile (reinstall.go)
return l.adopt(c.Box, c)
}
l.saveCreds(c)
l.sentClaim = claim
return nil
}
func zeroBits(sum []byte) int {
n := 0
for _, b := range sum {
if b == 0 {
n += 8
continue
}
return n + bits.LeadingZeros8(b)
}
return n
}
// ---- main loop (retries: from 10 s, doubling to 2 min, ±20 %)
const (
retryFirst = 10 * time.Second
retryMax = 2 * time.Minute
)
func jitter(d time.Duration) time.Duration {
return d + time.Duration((rand.Float64()*0.4-0.2)*float64(d))
}
func (l *link) loop(ctx context.Context) {
if testFleet().Disabled {
slog.Info("fleet off for this test VM (opt/cantabile/fleet): not enrolling")
<-ctx.Done()
return
}
wait := retryFirst
for ctx.Err() == nil {
l.connected = false
err := l.session(ctx)
if errors.Is(err, errBackToDirect) {
wait = retryFirst
continue
}
if l.connected {
wait = retryFirst
}
if errors.Is(err, errRevoked) {
slog.Warn("revoked: checking again in a day")
wait = 24 * time.Hour
} else if errors.Is(err, errClaim) {
slog.Warn("not enrolled: waiting for the owner's claim code", "reason", err.Error())
l.claimWait(ctx)
wait = retryFirst
continue
} else if err != nil {
slog.Warn("not connected", "error", err, "retry in", wait.String())
}
select {
case <-ctx.Done():
return
case <-time.After(jitter(wait)):
}
wait = min(wait*2, retryMax)
}
}
func (l *link) subject(kind string) string { return l.cfg.Prefix + ".site." + l.id + "." + kind }
// connectNATS: nats.Connect (tests replace it).
var connectNATS = nats.Connect
// sessionOn: credentials, connection, heartbeats until the connection or the
// credentials end, on the path l.eps[i] (endpoints.go).
func (l *link) sessionOn(ctx context.Context, i int) error {
c, ok := l.loadCreds()
switch {
case !ok:
if err := l.enrol(); err != nil {
return err
}
c, _ = l.loadCreds()
case time.Since(time.Unix(c.At, 0)) > time.Duration(c.RenewAfter)*time.Second:
if err := l.renew(); err != nil {
return err
}
c, _ = l.loadCreds()
case !l.renewed:
// Once per start: only a renew tells that this key is no longer the
// site's; if the platform cannot be reached, the saved credentials do.
if err := l.renew(); errors.Is(err, errRevoked) {
return err
} else if err != nil {
slog.Warn("renew at start", "error", err)
}
c, _ = l.loadCreds()
}
l.renewed = true
// The site's user may receive only its commands and the replies to its
// own requests (JetStream's acknowledgements): its own inbox prefix.
ep := l.ep()
nurl, onPath := natsURL(c.NATS, ep, l.eps)
opts := []nats.Option{nats.Name("cantabile-link " + l.id),
nats.CustomInboxPrefix("_INBOX_" + l.id),
nats.UserJWT(func() (string, error) { l.mu.Lock(); defer l.mu.Unlock(); return l.jwt, nil },
func(nonce []byte) ([]byte, error) { return l.kp.Sign(nonce) }),
nats.MaxReconnects(5), nats.ReconnectWait(5 * time.Second)}
if onPath && ep.tls != nil { // the direct path's pins hold for NATS too
opts = append(opts, nats.Secure(ep.tls.Clone()))
}
nc, err := connectNATS(withPort(nurl), opts...)
if err != nil {
if strings.Contains(err.Error(), "Authorization") || strings.Contains(err.Error(), "expired") {
os.Remove(filepath.Join(l.cfg.State, "creds.json"))
return l.renew()
}
return pathError{fmt.Errorf("nats %s: %w", nurl, err)}
}
js, err := nc.JetStream(nats.MaxWait(10 * time.Second))
if err != nil {
nc.Close()
return err
}
l.setConn(nc, js)
defer func() { l.setConn(nil, nil); nc.Close() }()
sub, err := nc.Subscribe(l.cfg.Prefix+".cmd."+l.id, l.onCommand)
if err != nil {
return err
}
defer sub.Unsubscribe()
slog.Info("connected", "site", l.id, "path", ep.Kind, "url", ep.URL)
l.connected = true
l.setState(true, "")
defer l.setState(false, "")
l.publish("hb", l.heartbeat())
if isHub() {
done := make(chan struct{})
defer close(done)
go l.hubReports(done)
}
hb := time.NewTicker(hbEvery)
defer hb.Stop()
renewAt := time.Unix(c.At, 0).Add(time.Duration(c.RenewAfter) * time.Second)
better, betterUp, stopBetter := l.betterPath(ctx, i)
defer stopBetter()
for {
select {
case <-ctx.Done():
return nil
case <-better:
if betterUp() {
return errBackToDirect
}
case <-hb.C:
if nc.IsClosed() {
return errors.New("connection closed")
}
l.publish("hb", l.heartbeat())
if time.Now().After(renewAt) || l.claim() != l.sentClaim {
if err := l.renew(); err != nil {
return err
}
renewAt = time.Now().Add(time.Duration(c.RenewAfter) * time.Second)
}
}
}
}
// publish sends a report (no acknowledgement); dropped while not connected.
func (l *link) publish(kind string, v any) {
nc, _ := l.conn()
if nc == nil {
return
}
b, _ := json.Marshal(v)
if err := nc.Publish(l.subject(kind), b); err != nil {
slog.Warn("publish", "kind", kind, "error", err)
}
}
// telemetry: one batch from the agent into JetStream; nil once the stream
// stored it (the agent deletes it from its queue only then). msgID lets
// JetStream drop a batch sent twice.
func (l *link) telemetry(data []byte, msgID string) error {
_, js := l.conn()
if js == nil {
return errors.New("not connected")
}
_, err := js.Publish(l.subject("tel"), data, nats.MsgId(msgID))
return err
}
func (l *link) heartbeat() map[string]any {
var hb map[string]any
if isHub() {
hb = l.hubHeartbeat()
} else {
hb = map[string]any{"v": 1, "version": version, "uptime": int64(time.Since(l.started).Seconds()),
"agent": l.loc.connected()}
}
if p := l.pathInfo(); p != nil {
hb["path"] = p
}
hb["consents"] = consents(env("CANTABILE_CONSENT_FILE",
map[bool]string{true: "/data/cantabile/edge/consent.json", false: "/data/state/consent.json"}[isHub()]))
return hb
}
// consents: the owner's consents as fleet keeps them (per
// recipient; nothing goes to a recipient without its yes): share (with
// Cantabile), control, and the recipients granted (building, grid,
// government), per add-on (the Hub's store), and how and when the site's
// was given. The agent's file, written by the panel or, on an HA add-on
// site, by addon-run from the add-on's configuration.
func consents(path string) map[string]any {
var c struct {
Share, Control bool
Recipients map[string]struct{ Granted bool }
Addons map[string]map[string]any `json:"addons"`
At int64 `json:"at"`
By string `json:"by"`
Source string `json:"source"`
TextVersion string `json:"text_version"`
}
b, _ := os.ReadFile(path)
json.Unmarshal(b, &c)
granted := []string{}
for k, v := range c.Recipients {
if v.Granted {
granted = append(granted, k)
}
}
sort.Strings(granted)
out := map[string]any{"share": c.Share, "control": c.Control, "recipients": granted}
// per add-on (the Hub's store: given when installing it), as recorded
if len(c.Addons) > 0 {
out["addons"] = c.Addons
}
// how and when it was given, and the texts' version (the panel, or the
// HA add-on's configuration at installation)
if c.At > 0 {
out["at"] = c.At
}
for k, v := range map[string]string{"by": c.By, "source": c.Source, "text_version": c.TextVersion} {
if v != "" {
out[k] = v
}
}
return out
}
// ---- commands (signed by the command key, for this site, not
// expired, each id done once)
type command struct {
V int `json:"v"`
ID string `json:"id"`
Box string `json:"box"`
Cmd string `json:"cmd"`
Args map[string]string `json:"args"`
Expires int64 `json:"expires"`
}
func verify(key crypto.PublicKey, payload, sig []byte) bool {
sum := sha256.Sum256(payload)
switch k := key.(type) {
case *ecdsa.PublicKey:
return ecdsa.VerifyASN1(k, sum[:], sig)
case *rsa.PublicKey:
return rsa.VerifyPKCS1v15(k, crypto.SHA256, sum[:], sig) == nil
}
return false
}
// checkCommand: the command in a message, if it is signed, for this site
// and not expired.
func checkCommand(key crypto.PublicKey, site string, data []byte, now time.Time) (command, error) {
var w struct{ P, Sig string }
var c command
if json.Unmarshal(data, &w) != nil {
return c, errors.New("not a command")
}
payload, err1 := base64.StdEncoding.DecodeString(w.P)
sig, err2 := base64.StdEncoding.DecodeString(w.Sig)
if err1 != nil || err2 != nil || !verify(key, payload, sig) {
return c, errors.New("bad signature")
}
if json.Unmarshal(payload, &c) != nil || c.Box != site || c.ID == "" {
return c, errors.New("not for this site")
}
if now.Unix() > c.Expires {
return c, errors.New("expired")
}
return c, nil
}
func (l *link) onCommand(m *nats.Msg) {
if isHub() {
var w struct{ T string }
json.Unmarshal(m.Data, &w)
switch w.T {
case "term": // terminal keystrokes: checked with the session key (terminal.go)
l.termInput(m.Data)
return
case "panel": // support's page requests: checked with the session key (panel.go)
l.panelRequest(m.Data)
return
}
}
c, err := checkCommand(l.cert, l.id, m.Data, time.Now())
if err != nil {
slog.Warn("command refused", "why", err.Error(), "id", c.ID)
return
}
l.doneMu.Lock()
defer l.doneMu.Unlock()
if r, ok := l.done(c.ID); ok { // sent again: answer again, do not do it twice
l.publish("result", r)
return
}
slog.Info("command", "id", c.ID, "cmd", c.Cmd)
ok, msg, after := l.do(c)
r := map[string]any{"v": 1, "id": c.ID, "ok": ok, "result": map[string]any{"message": msg}}
l.remember(c.ID, r)
l.publish("result", r)
if nc, _ := l.conn(); nc != nil {
nc.Flush()
}
if after != nil { // a restart: after the answer went out
go after()
}
}
// do: the link's own commands (on the Hub also the box's, hubcmd.go); the
// agent's (mode, control, limits) go to it over the local socket
// and its answer comes back.
func (l *link) do(c command) (bool, string, func()) {
if isHub() {
if handled, ok, msg, after := l.hubDo(c); handled {
return ok, msg, after
}
}
switch c.Cmd {
case "site-moved", "restore-offer": // a reinstall merged into its earlier site (reinstall.go)
return l.reinstallCmd(c)
case "refresh":
l.publish("hb", l.heartbeat())
return true, "heartbeat sent", nil
case "tariff", "model", "flats", "acl": // data bundles: checked here, read by the agent (bundles.go; flats: a building's box; acl: the devices' protection)
ok, msg := l.bundleCmd(c, time.Now())
if ok && c.Cmd == "acl" && isHub() {
devicesPolicy() // the policy in force for add-ons and the Modbus bridge (/usr/lib/cantabile/devices)
}
return ok, msg, nil
case "building": // an emergency only with the grid operator's proof (gridorder.go)
if err := l.buildingCmd(&c, time.Now()); err != nil {
return false, "refused: " + err.Error(), nil
}
}
ok, msg := l.loc.command(c, 30*time.Second)
return ok, msg, nil
}
// done commands (last 200), so a command sent again is answered, not done
// again, also across restarts.
func (l *link) done(id string) (map[string]any, bool) {
var d map[string]map[string]any
b, _ := os.ReadFile(filepath.Join(l.cfg.State, "done.json"))
json.Unmarshal(b, &d)
r, ok := d[id]
return r, ok
}
func (l *link) remember(id string, r map[string]any) {
var d map[string]map[string]any
p := filepath.Join(l.cfg.State, "done.json")
b, _ := os.ReadFile(p)
json.Unmarshal(b, &d)
if d == nil {
d = map[string]map[string]any{}
}
r["at"] = time.Now().Unix()
d[id] = r
if len(d) > 200 {
type kv struct {
k string
at float64
}
var all []kv
for k, v := range d {
at, _ := v["at"].(float64)
if n, ok := v["at"].(int64); ok {
at = float64(n)
}
all = append(all, kv{k, at})
}
sort.Slice(all, func(i, j int) bool { return all[i].at < all[j].at })
for _, x := range all[:len(all)-200] {
delete(d, x.k)
}
}
nb, _ := json.Marshal(d)
os.WriteFile(p+".tmp", nb, 0o600)
os.Rename(p+".tmp", p)
}
+255
View File
@@ -0,0 +1,255 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"bufio"
"crypto/ecdsa"
"crypto/elliptic"
"crypto/rand"
"crypto/sha256"
"encoding/base64"
"encoding/json"
"errors"
"net"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"testing"
"time"
"github.com/nats-io/nkeys"
)
func TestWithPort(t *testing.T) {
for in, want := range map[string]string{
"wss://devices.cantabile.cloud/nats": "wss://devices.cantabile.cloud:443/nats",
"wss://devices.cantabile.cloud:443/nats": "wss://devices.cantabile.cloud:443/nats",
"ws://192.0.2.1/nats": "ws://192.0.2.1:80/nats",
"nats://nats:4222": "nats://nats:4222",
} {
if got := withPort(in); got != want {
t.Errorf("%s: %s, want %s", in, got, want)
}
}
}
func TestSiteIDFromHA(t *testing.T) {
d := t.TempDir()
p := filepath.Join(d, "core.uuid")
os.WriteFile(p, []byte(`{"version":1,"key":"core.uuid","data":{"uuid":"8B7C0F9E5A1D4C2B9E3F0A1B2C3D4E5F"}}`), 0o600)
id, err := siteID(config{HAUUID: p})
if err != nil || !siteIDRE.MatchString(id) {
t.Fatalf("%q %v", id, err)
}
// case does not matter; the raw uuid never shows
os.WriteFile(p, []byte(`{"data":{"uuid":"8b7c0f9e5a1d4c2b9e3f0a1b2c3d4e5f"}}`), 0o600)
if id2, _ := siteID(config{HAUUID: p}); id2 != id || strings.Contains(id, "8b7c0f9e") {
t.Errorf("%s %s", id, id2)
}
if _, err := siteID(config{SiteID: "nothex"}); err == nil {
t.Error("bad CANTABILE_SITE_ID taken")
}
}
func TestSolve(t *testing.T) {
var ch challenge
ch.Challenge, ch.Bits = "abc", 4
ch.Scrypt.N, ch.Scrypt.R, ch.Scrypt.P, ch.Scrypt.Len, ch.Scrypt.Salt = 1024, 8, 1, 32, "s"
n := solve(ch)
if n < 0 {
t.Fatal(n)
}
}
func signed(t *testing.T, k *ecdsa.PrivateKey, c command) []byte {
p, _ := json.Marshal(c)
sum := sha256.Sum256(p)
sig, err := ecdsa.SignASN1(rand.Reader, k, sum[:])
if err != nil {
t.Fatal(err)
}
b, _ := json.Marshal(map[string]string{"p": base64.StdEncoding.EncodeToString(p), "sig": base64.StdEncoding.EncodeToString(sig)})
return b
}
func TestCheckCommand(t *testing.T) {
k, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
other, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
site := strings.Repeat("ab", 16)
now := time.Now()
good := command{V: 1, ID: "c1", Box: site, Cmd: "refresh", Expires: now.Add(time.Hour).Unix()}
if _, err := checkCommand(&k.PublicKey, site, signed(t, k, good), now); err != nil {
t.Errorf("good: %v", err)
}
if _, err := checkCommand(&k.PublicKey, site, signed(t, other, good), now); err == nil || err.Error() != "bad signature" {
t.Errorf("other key: %v", err)
}
wrong := good
wrong.Box = strings.Repeat("cd", 16)
if _, err := checkCommand(&k.PublicKey, site, signed(t, k, wrong), now); err == nil || err.Error() != "not for this site" {
t.Errorf("other site: %v", err)
}
old := good
old.Expires = now.Add(-time.Minute).Unix()
if _, err := checkCommand(&k.PublicKey, site, signed(t, k, old), now); err == nil || err.Error() != "expired" {
t.Errorf("expired: %v", err)
}
// a changed payload under the old signature
var w map[string]string
json.Unmarshal(signed(t, k, good), &w)
p, _ := json.Marshal(command{V: 1, ID: "c1", Box: site, Cmd: "mode", Expires: good.Expires})
w["p"] = base64.StdEncoding.EncodeToString(p)
b, _ := json.Marshal(w)
if _, err := checkCommand(&k.PublicKey, site, b, now); err == nil {
t.Error("tampered payload taken")
}
}
func TestDoneOnce(t *testing.T) {
l := &link{cfg: config{State: t.TempDir()}}
l.remember("c1", map[string]any{"ok": true})
if r, ok := l.done("c1"); !ok || r["ok"] != true {
t.Errorf("%v %v", r, ok)
}
for i := 0; i < 205; i++ {
l.remember(strings.Repeat("x", i+1), map[string]any{"ok": true})
}
var d map[string]any
b, _ := os.ReadFile(filepath.Join(l.cfg.State, "done.json"))
json.Unmarshal(b, &d)
if len(d) != 200 {
t.Errorf("kept %d", len(d))
}
}
// The local socket: hello, telemetry without a connection (not stored, so
// no acknowledgement), and a command answered by the agent.
func TestLocalSocket(t *testing.T) {
l := &link{id: strings.Repeat("ab", 16)}
p := filepath.Join(t.TempDir(), "link.sock")
lc, err := listen(l, p)
if err != nil {
t.Fatal(err)
}
defer lc.close()
l.loc = lc
c, err := net.Dial("unix", p)
if err != nil {
t.Fatal(err)
}
defer c.Close()
r := bufio.NewScanner(c)
read := func() msg {
c.SetReadDeadline(time.Now().Add(5 * time.Second))
if !r.Scan() {
t.Fatal("no answer")
}
var m msg
json.Unmarshal(r.Bytes(), &m)
return m
}
c.Write([]byte(`{"op":"hello"}` + "\n"))
if m := read(); m.Site != l.id {
t.Errorf("hello: %+v", m)
}
c.Write([]byte(`{"op":"tel","id":7,"msg_id":"x:1","data":{"a":1}}` + "\n"))
if m := read(); m.Op != "ack" || m.OK == nil || *m.OK || string(m.ID) != "7" {
t.Errorf("tel without connection: %+v", m)
}
for i := 0; i < 50 && !lc.connected(); i++ {
time.Sleep(10 * time.Millisecond)
}
done := make(chan [2]any, 1)
go func() {
ok, m := lc.command(command{ID: "c9", Cmd: "mode", Args: map[string]string{"mode": "shadow"}}, 5*time.Second)
done <- [2]any{ok, m}
}()
m := read()
if m.Op != "command" || m.Cmd != "mode" || m.Args["mode"] != "shadow" {
t.Fatalf("command: %+v", m)
}
c.Write([]byte(`{"op":"result","id":"c9","ok":true,"message":"already shadow"}` + "\n"))
if got := <-done; got[0] != true || got[1] != "already shadow" {
t.Errorf("result: %v", got)
}
}
// TestEnrolClaim: the claim code goes with the enrolment; a refusal for the
// code is errClaim and noted for the panel, cleared once enrolled.
func TestEnrolClaim(t *testing.T) {
var sent string
refuse := true
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path == "/api/devices/challenge" {
w.Write([]byte(`{"challenge":"c","bits":0,"scrypt":{"n":2,"r":1,"p":1,"len":8,"salt":"s"}}`))
return
}
var in struct{ Claim string }
json.NewDecoder(r.Body).Decode(&in)
sent = in.Claim
if refuse {
w.WriteHeader(403)
w.Write([]byte(`{"error":"claim code required"}`))
return
}
w.Write([]byte(`{"box":"x","jwt":"j","nats":"wss://n","renew_after":60}`))
}))
defer srv.Close()
dir := t.TempDir()
kp, _ := nkeys.CreateUser()
l := &link{cfg: config{URL: srv.URL, State: dir, Claim: filepath.Join(dir, "claim-code")}, kp: kp, id: "x"}
if err := l.enrol(); !errors.Is(err, errClaim) || sent != "" {
t.Fatalf("no code: %v, sent %q", err, sent)
}
if b, _ := os.ReadFile(filepath.Join(dir, "enrol-refused")); string(b) != "claim code required\n" {
t.Fatalf("state %q", b)
}
os.WriteFile(l.cfg.Claim, []byte("ABCD-EFGH-JKLM\n"), 0o600)
refuse = false
if err := l.enrol(); err != nil || sent != "ABCD-EFGH-JKLM" {
t.Fatalf("with code: %v, sent %q", err, sent)
}
if _, err := os.Stat(filepath.Join(dir, "enrol-refused")); !os.IsNotExist(err) {
t.Fatal("refusal still noted")
}
}
// Before cantabile-update's first check after a boot there is no
// update.json: the reports say "not-checked", not null; after it, its state.
func TestUpdateState(t *testing.T) {
p := filepath.Join(t.TempDir(), "update.json")
if st, av := updateState(p); st != "not-checked" || av != nil {
t.Errorf("no file: %v, %v", st, av)
}
os.WriteFile(p, []byte(`{"state": "up-to-date", "available": "0.1.0-dev.20"}`), 0o644)
if st, av := updateState(p); st != "up-to-date" || av != "0.1.0-dev.20" {
t.Errorf("after a check: %v, %v", st, av)
}
}
// The owner's consents as the heartbeat carries them: what, and how and
// when it was given (the HA add-on's configuration at installation).
func TestConsentsCarrySourceAndVersion(t *testing.T) {
p := filepath.Join(t.TempDir(), "consent.json")
os.WriteFile(p, []byte(`{"share": true, "control": false, "at": 1767000000, "by": "ha-addon-config",
"source": "given at installation in the add-on's configuration", "text_version": "working-2026-10-29",
"recipients": {"building": {"granted": true}, "grid": {"granted": false}},
"addons": {"modbus-bridge": {"granted": true, "control": true, "text_version": "working-2026-10-29"}}}`), 0o600)
c := consents(p)
if c["share"] != true || c["control"] != false || c["at"] != int64(1767000000) || c["by"] != "ha-addon-config" ||
c["text_version"] != "working-2026-10-29" || !strings.Contains(c["source"].(string), "installation") {
t.Fatalf("consents: %v", c)
}
if a := c["addons"].(map[string]map[string]any)["modbus-bridge"]; a["granted"] != true || a["control"] != true {
t.Fatalf("addons: %v", c["addons"])
}
if r := c["recipients"].([]string); len(r) != 1 || r[0] != "building" {
t.Fatalf("recipients: %v", r)
}
if c := consents(filepath.Join(t.TempDir(), "none.json")); c["share"] != false || c["at"] != nil || c["by"] != nil {
t.Fatalf("no file: %v", c)
}
}
+279
View File
@@ -0,0 +1,279 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"bytes"
"crypto/hmac"
"crypto/rand"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"fmt"
"io"
"log/slog"
"net/http"
"os"
"strconv"
"strings"
"sync"
"time"
)
// Cantabile support in the owner's panel through Cantabile's console:
// opened by a signed "panel-open" command carrying a random session key, like
// the terminal. Each page request comes on ctb.cmd.<id> as {"t":"panel", ...}
// with an HMAC of that key; the agent asks the panel's support listener on
// 127.0.0.1 (/usr/lib/cantabile/web, SupportServer) with a token of its own (kept
// as sha256 in /run/cantabile/agent-panel.json) and sends the answer to
// ctb.site.<id>.panel. The same limits as the terminal: 15 minutes without a
// request, 1 hour for the Cantabile team, the owner's permission's end otherwise;
// the owner's End now closes it (closeAll).
const (
panelURL = "http://127.0.0.1:8091"
panelState = "/run/cantabile/agent-panel.json"
panelBodyMax = 64 << 10 // a form from the console
panelAnsMax = 900 << 10 // an answer (NATS' message limit is 1 MiB)
)
type panelSession struct {
id, by, consent string
key []byte
token string // what the panel checks (sha256 in panelState)
until time.Time // the owner's permission's end, or started+1h
started time.Time
once sync.Once
mu sync.Mutex
seq int64
last time.Time
}
// panelMsg: one page request from the console.
type panelMsg struct {
T string `json:"t"` // "panel"
S string `json:"s"`
N int64 `json:"n"`
M string `json:"m"` // GET, POST
P string `json:"p"` // path and query
CT string `json:"ct,omitempty"` // a form's content type
B string `json:"b,omitempty"` // base64 body
Close bool `json:"close,omitempty"`
MAC string `json:"mac"`
}
// panelMAC: what the console signs each request with (session key).
func panelMAC(key []byte, m panelMsg) string {
h := hmac.New(sha256.New, key)
fmt.Fprintf(h, "%s|%d|%s|%s|%s|%s|%t", m.S, m.N, m.M, m.P, m.CT, m.B, m.Close)
return hex.EncodeToString(h.Sum(nil))
}
// panelURLFor: the panel's support listener for a path (a test server in tests).
var panelURLFor = func(p string) string { return panelURL + p }
var (
panelsMu sync.Mutex
panels = map[string]*panelSession{}
)
// writePanelState: the open sessions' token hashes for the panel.
func writePanelState() {
panelsMu.Lock()
list := []map[string]any{}
for _, s := range panels {
h := sha256.Sum256([]byte(s.token))
list = append(list, map[string]any{"hash": hex.EncodeToString(h[:]), "until": s.until.Unix(), "by": s.by})
}
panelsMu.Unlock()
b, _ := json.Marshal(map[string]any{"sessions": list})
// the panel's user reads it; the tokens themselves never leave the agent
os.WriteFile(panelState+".tmp", b, 0o644)
os.Rename(panelState+".tmp", panelState)
}
// panelSessions: the open panel sessions for the owner's banner (writeTermState).
func panelSessions() []map[string]any {
panelsMu.Lock()
defer panelsMu.Unlock()
out := []map[string]any{}
for _, s := range panels {
out = append(out, map[string]any{"by": s.by, "since": s.started.Unix(), "consent": s.consent, "kind": "panel"})
}
return out
}
func (l *link) panelOpen(c command) (bool, string) {
id, keyHex := c.Args["session"], c.Args["key"]
key, err := hex.DecodeString(keyHex)
if err != nil || len(key) != 32 || id == "" {
return false, "bad session"
}
until := time.Now().Add(termMax)
if c.Args["consent"] != "" {
u, err := strconv.ParseInt(c.Args["until"], 10, 64)
if err != nil || time.Now().Unix() >= u {
return false, "the owner's permission has ended"
}
until = time.Unix(u, 0)
}
panelsMu.Lock()
if _, ok := panels[id]; ok {
panelsMu.Unlock()
return true, "already open"
}
panelsMu.Unlock()
tok := make([]byte, 32)
rand.Read(tok)
s := &panelSession{id: id, by: c.Args["by"], consent: c.Args["consent"], key: key, token: hex.EncodeToString(tok),
until: until, started: time.Now(), last: time.Now()}
panelsMu.Lock()
panels[id] = s
panelsMu.Unlock()
writePanelState()
writeTermState()
why := "Cantabile support opened your panel through Cantabile's console (" + s.by + ")"
if s.consent != "" {
why += ", as you allowed in request " + s.consent
}
event("remote-panel", why)
slog.Info("panel open", "session", id, "by", s.by)
go l.panelWatch(s)
return true, "panel open"
}
// panelEnd: why a session must close now ("" while it may stay open).
func panelEnd(last, until, now time.Time) string {
switch {
case now.Sub(last) > termIdle:
return "closed after 15 minutes without a request"
case !now.Before(until):
return "closed: its time (or the owner's permission) ended"
}
return ""
}
func (l *link) panelWatch(s *panelSession) {
t := time.NewTicker(10 * time.Second)
defer t.Stop()
for range t.C {
panelsMu.Lock()
_, open := panels[s.id]
panelsMu.Unlock()
if !open {
return
}
s.mu.Lock()
last := s.last
s.mu.Unlock()
if why := panelEnd(last, s.until, time.Now()); why != "" {
l.panelClose(s, why)
return
}
}
}
func (l *link) panelClose(s *panelSession, why string) {
s.once.Do(func() {
panelsMu.Lock()
delete(panels, s.id)
panelsMu.Unlock()
writePanelState()
writeTermState()
l.publish("panel", map[string]any{"s": s.id, "end": true, "why": why})
event("remote-panel", "Cantabile support's panel session closed ("+why+")")
slog.Info("panel closed", "session", s.id, "why", why)
})
}
// closePanels: the owner pressed End now.
func (l *link) closePanels() {
panelsMu.Lock()
var all []*panelSession
for _, s := range panels {
all = append(all, s)
}
panelsMu.Unlock()
for _, s := range all {
l.panelClose(s, "ended by the owner")
}
}
// panelRequest: one page request from the console (checked with the key):
// asked of the panel, answered on ctb.site.<id>.panel.
func (l *link) panelRequest(raw []byte) {
var m panelMsg
if json.Unmarshal(raw, &m) != nil {
return
}
panelsMu.Lock()
s := panels[m.S]
panelsMu.Unlock()
if s == nil {
if m.S != "" {
l.publish("panel", map[string]any{"s": m.S, "n": m.N, "end": true, "why": "no such session on the box"})
}
return
}
if !hmac.Equal([]byte(panelMAC(s.key, m)), []byte(m.MAC)) {
return
}
s.mu.Lock()
fresh := m.N > s.seq
if fresh {
s.seq, s.last = m.N, time.Now()
}
s.mu.Unlock()
if !fresh {
return
}
if m.Close {
l.panelClose(s, "closed in Cantabile's console")
return
}
go l.publish("panel", panelAsk(s, m))
}
// panelAsk: the request to the panel's support listener; the answer as
// the console gets it (status, type, redirect, body).
func panelAsk(s *panelSession, m panelMsg) map[string]any {
ans := map[string]any{"s": s.id, "n": m.N}
if (m.M != "GET" && m.M != "POST") || !strings.HasPrefix(m.P, "/") || strings.HasPrefix(m.P, "//") {
ans["status"] = 400
return ans
}
body, err := base64.StdEncoding.DecodeString(m.B)
if err != nil || len(body) > panelBodyMax {
ans["status"] = 413
return ans
}
req, _ := http.NewRequest(m.M, panelURLFor(m.P), bytes.NewReader(body))
if m.M == "POST" {
ct := m.CT
if ct == "" {
ct = "application/x-www-form-urlencoded"
}
req.Header.Set("Content-Type", ct)
}
req.Header.Set("X-Cantabile-Support", s.token)
cl := &http.Client{Timeout: 60 * time.Second,
CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
res, err := cl.Do(req)
if err != nil {
ans["status"], ans["err"] = 502, "the panel did not answer: "+err.Error()
return ans
}
defer res.Body.Close()
b, _ := io.ReadAll(io.LimitReader(res.Body, panelAnsMax+1))
if len(b) > panelAnsMax {
ans["status"], ans["err"] = 502, "the page is too large to pass on"
return ans
}
ans["status"], ans["ct"], ans["b"] = res.StatusCode, res.Header.Get("Content-Type"), base64.StdEncoding.EncodeToString(b)
if l := res.Header.Get("Location"); l != "" {
ans["loc"] = l
}
return ans
}
+61
View File
@@ -0,0 +1,61 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"encoding/base64"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
)
// Cantabile support's page requests: the key's MAC, the
// panel's own answer passed on, never a redirect followed, nothing but
// GET and POST to a path.
func TestPanelAsk(t *testing.T) {
var got *http.Request
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
got = r
if r.URL.Path == "/lan" && r.Method == "POST" {
w.Header().Set("Location", "/lan?ok=1")
w.WriteHeader(303)
return
}
w.Header().Set("Content-Type", "text/html")
w.Write([]byte("<a href=\"/wifi\">Wi-Fi</a>"))
}))
defer srv.Close()
s := &panelSession{id: "s1", token: strings.Repeat("ab", 32), key: []byte(strings.Repeat("k", 32))}
old := panelURLFor
panelURLFor = func(p string) string { return srv.URL + p }
defer func() { panelURLFor = old }()
a := panelAsk(s, panelMsg{S: "s1", N: 1, M: "GET", P: "/status?x=1"})
if a["status"] != 200 || got.Header.Get("X-Cantabile-Support") != s.token || got.URL.RequestURI() != "/status?x=1" {
t.Fatalf("GET: %v %v", a, got)
}
b, _ := base64.StdEncoding.DecodeString(a["b"].(string))
if string(b) != "<a href=\"/wifi\">Wi-Fi</a>" || a["ct"] != "text/html" {
t.Fatalf("body: %q %v", b, a["ct"])
}
a = panelAsk(s, panelMsg{S: "s1", N: 2, M: "POST", P: "/lan", B: base64.StdEncoding.EncodeToString([]byte("do=keep"))})
if a["status"] != 303 || a["loc"] != "/lan?ok=1" || got.Header.Get("Content-Type") != "application/x-www-form-urlencoded" {
t.Fatalf("POST: %v", a)
}
for _, bad := range []panelMsg{{M: "DELETE", P: "/"}, {M: "GET", P: "//evil.example/"}, {M: "GET", P: "status"}} {
if a := panelAsk(s, bad); a["status"] != 400 {
t.Fatalf("%+v: %v", bad, a)
}
}
key := []byte(strings.Repeat("k", 32))
m := panelMsg{S: "s1", N: 3, M: "GET", P: "/"}
if panelMAC(key, m) == panelMAC(key, panelMsg{S: "s1", N: 3, M: "GET", P: "/x"}) {
t.Fatal("the MAC does not cover the path")
}
now := time.Now()
if panelEnd(now, now.Add(time.Hour), now) != "" || panelEnd(now.Add(-16*time.Minute), now.Add(time.Hour), now) == "" ||
panelEnd(now, now.Add(-time.Second), now) == "" {
t.Fatal("panelEnd")
}
}
+119
View File
@@ -0,0 +1,119 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
// A reinstall recognised by fleet (platform/services/fleet/reinstall.go):
// this box's new installation was merged into its earlier site. Fleet says
// so in the credentials of an enrolment or renewal ("box": the earlier
// site's id) or with the signed command "site-moved" {"site"}; the link then
// keeps that id (adoptedFile; on the Hub also the site-id file the other
// tools read) and starts again under it, and the agent with it.
//
// "restore-offer" {"offer": JSON}: what the cloud still has of the earlier
// site that the owner may take back (the update channel, the add-ons, the
// earlier consents: never applied here; the panel or the add-on's page asks
// the owner). Kept as restore-offer.json in the link's state directory.
import (
"encoding/json"
"log/slog"
"os"
"os/exec"
"path/filepath"
"time"
)
const (
adoptedFile = "adopted-site-id"
offerFile = "restore-offer.json"
)
// exitProcess: the link ends so its service (or the add-on's container)
// starts it again under the adopted id.
var exitProcess = func() {
time.Sleep(2 * time.Second)
if isHub() {
exec.Command("systemctl", "restart", "--no-block", "cantabile-edge.service").Run()
}
os.Exit(75)
}
// adoptSite: writes the earlier site's id where this box's tools read it.
func (l *link) adoptSite(id string) error {
if !siteIDRE.MatchString(id) {
return errBadSite
}
p := filepath.Join(l.cfg.State, adoptedFile)
if err := os.WriteFile(p+".tmp", []byte(id+"\n"), 0o644); err != nil {
return err
}
if err := os.Rename(p+".tmp", p); err != nil {
return err
}
os.WriteFile(filepath.Join(l.cfg.State, "site-id"), []byte(id+"\n"), 0o644)
if isHub() {
os.WriteFile(hubSiteIDFile, []byte(id+"\n"), 0o644)
os.WriteFile(filepath.Join(filepath.Dir(l.cfg.Socket), "site-id"), []byte(id+"\n"), 0o644)
}
slog.Info("this box is now its earlier site", "site", id, "was", l.id)
return nil
}
type errString string
func (e errString) Error() string { return string(e) }
const errBadSite = errString("not a site id")
// adopt: credentials for the earlier site came back: kept, then the link
// starts again under that id.
func (l *link) adopt(id string, c creds) error {
if err := l.adoptSite(id); err != nil {
return err
}
old := l.id
l.id = id
l.saveCreds(c)
l.enrolState("")
hubEvent("reinstall", "Cantabile recognised this box as the earlier site "+id+" (was "+old+"); starting again")
go exitProcess()
return errString("site moved: restarting")
}
func (l *link) reinstallCmd(c command) (bool, string, func()) {
switch c.Cmd {
case "site-moved":
id := c.Args["site"]
if err := l.adoptSite(id); err != nil {
return false, err.Error(), nil
}
// The next start enrols or renews under the earlier id with this
// key (fleet moved it there).
os.Remove(filepath.Join(l.cfg.State, "creds.json"))
hubEvent("reinstall", "Cantabile merged this box into its earlier site "+id+"; starting again")
return true, "now site " + id + "; restarting", exitProcess
case "restore-offer":
var offer map[string]any
if json.Unmarshal([]byte(c.Args["offer"]), &offer) != nil || offer["from"] == nil {
return false, "not an offer", nil
}
offer["received"] = time.Now().Unix()
b, _ := json.MarshalIndent(offer, "", " ")
p := filepath.Join(l.cfg.State, offerFile)
if err := os.WriteFile(p+".tmp", b, 0o644); err != nil {
return false, err.Error(), nil
}
os.Rename(p+".tmp", p)
hubEvent("reinstall", "Cantabile offers the earlier site's settings: see the panel")
return true, "offer kept for the owner", nil
}
return false, "unknown", nil
}
// hubEvent: into the box's event log (the Hub's; the add-on logs only).
func hubEvent(kind, msg string) {
slog.Info(msg, "kind", kind)
if isHub() {
event(kind, msg)
}
}
+49
View File
@@ -0,0 +1,49 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"encoding/json"
"os"
"regexp"
"strings"
)
// The box's serial and the tests' fleet settings (boxes must be told
// apart, and test VMs must not pile up in a fleet).
// serialFile: written once on the Hub's first boot by /usr/lib/cantabile/serial
// (cantabile-serial.service), from the hardware: CTB-XXXX-XXXX.
var serialFile = "/data/cantabile/serial"
var serialRE = regexp.MustCompile(`^CTB-[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}$`)
// boxSerial: the Hub's serial ("" in the add-on, or before the file exists).
func boxSerial() string {
if !isHub() {
return ""
}
if s := strings.TrimSpace(read(serialFile)); serialRE.MatchString(s) {
return s
}
return ""
}
// fleetFwCfg: QEMU's opt/cantabile/fleet, set only by the tests' VMs
// (hub-qemu.sh, qemu-run.sh): {"test": true} enrols tagged "test" (fleet hides
// such boxes and revokes them a day after they went offline); {"disabled":
// true} never enrols. Real hardware has no fw_cfg.
var fleetFwCfg = "/sys/firmware/qemu_fw_cfg/by_name/opt/cantabile/fleet/raw"
type fleetSettings struct {
Disabled bool `json:"disabled"`
Test bool `json:"test"`
}
func testFleet() fleetSettings {
var s fleetSettings
if b, err := os.ReadFile(fleetFwCfg); err == nil {
json.Unmarshal(b, &s)
}
return s
}
+79
View File
@@ -0,0 +1,79 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"os"
"path/filepath"
"testing"
)
// The serial only on the Hub and only a valid one; the tests' fleet
// settings from QEMU's fw_cfg (none on real hardware).
func TestSerialAndTestFleet(t *testing.T) {
d := t.TempDir()
oldS, oldF := serialFile, fleetFwCfg
defer func() { serialFile, fleetFwCfg = oldS, oldF }()
serialFile, fleetFwCfg = filepath.Join(d, "serial"), filepath.Join(d, "fleet")
t.Setenv("CANTABILE_HUB", "1")
if s := boxSerial(); s != "" {
t.Fatalf("no file: %q", s)
}
os.WriteFile(serialFile, []byte("CTB-7K3M-Q9XA\n"), 0o644)
if s := boxSerial(); s != "CTB-7K3M-Q9XA" {
t.Fatalf("serial: %q", s)
}
os.WriteFile(serialFile, []byte("CTB-0000-Q9XA\n"), 0o644)
if s := boxSerial(); s != "" {
t.Fatalf("bad serial taken: %q", s)
}
t.Setenv("CANTABILE_HUB", "")
os.WriteFile(serialFile, []byte("CTB-7K3M-Q9XA\n"), 0o644)
if s := boxSerial(); s != "" {
t.Fatalf("serial outside the Hub: %q", s)
}
if f := testFleet(); f.Test || f.Disabled {
t.Fatalf("no fw_cfg: %+v", f)
}
os.WriteFile(fleetFwCfg, []byte(`{"test": true}`), 0o644)
if f := testFleet(); !f.Test || f.Disabled {
t.Fatalf("test: %+v", f)
}
os.WriteFile(fleetFwCfg, []byte(`{"disabled": true}`), 0o644)
if f := testFleet(); !f.Disabled {
t.Fatalf("disabled: %+v", f)
}
}
// A Hub's site id comes from its hardware file, without HA; a site with its
// own HA keeps HA's instance id.
func TestSiteIDHub(t *testing.T) {
d := t.TempDir()
old := hubSiteIDFile
defer func() { hubSiteIDFile = old }()
hubSiteIDFile = filepath.Join(d, "site-id")
ha := filepath.Join(d, "core.uuid")
os.WriteFile(ha, []byte(`{"data": {"uuid": "0123456789abcdef0123456789abcdef"}}`), 0o644)
cfg := config{HAUUID: ha}
t.Setenv("CANTABILE_HUB", "")
fromHA, err := siteID(cfg)
if err != nil || !siteIDRE.MatchString(fromHA) {
t.Fatalf("add-on: %q %v", fromHA, err)
}
t.Setenv("CANTABILE_HUB", "1")
if _, err := siteID(config{HAUUID: filepath.Join(d, "none")}); err == nil {
t.Fatal("a Hub without its site-id file must not start (cantabile-serial writes it first)")
}
os.WriteFile(hubSiteIDFile, []byte("5e1f00aa5e1f00aa5e1f00aa5e1f00aa\n"), 0o644)
id, err := siteID(config{HAUUID: filepath.Join(d, "none")}) // no HA at all
if err != nil || id != "5e1f00aa5e1f00aa5e1f00aa5e1f00aa" {
t.Fatalf("hub: %q %v", id, err)
}
if id == fromHA {
t.Fatal("the Hub used HA's id")
}
}
+31
View File
@@ -0,0 +1,31 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"strings"
"testing"
"github.com/nats-io/nkeys"
)
// The site's key signs a support request or a building request of this
// site, nothing else (fleet joining.go checks "building:<site>:<ts>:<sha256>").
func TestSignFor(t *testing.T) {
kp, _ := nkeys.CreateUser()
seed, _ := kp.Seed()
id := strings.Repeat("a", 32)
h := strings.Repeat("0f", 32)
for text, ok := range map[string]bool{
"support-ticket:" + id + ":X:1": true,
"building:" + id + ":1793262682:" + h: true,
"building:" + strings.Repeat("b", 32) + ":1:" + h: false, // another site
"building:" + id + ":1:" + h[:10]: false, // not a sha256
"building:" + id + ":1:" + h + ":more": false,
"renew:" + id + ":1": false,
} {
if _, err := signFor(id, seed, text); (err == nil) != ok {
t.Errorf("%s: signed %v", text, err == nil)
}
}
}
+272
View File
@@ -0,0 +1,272 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"fmt"
"log/slog"
"os"
"os/exec"
"strconv"
"sync"
"time"
"github.com/creack/pty"
)
// Remote terminal (docs/device-api.md): a root shell opened by a signed
// "terminal-open" command, which carries a random session key. Keystrokes
// come on ctb.cmd.<id> as {"t":"term", ...} with an HMAC of that key; the
// screen goes to ctb.site.<id>.term. Closed after 15 min without input, and
// after 1 hour in any case; a session on the owner's permission (consent)
// lasts until that permission ends ("until", 2 hours from the owner's yes) and no longer. The console keeps the full transcript; the box
// logs opening and closing in its event log.
const (
termIdle = 15 * time.Minute
termMax = time.Hour
)
type termSession struct {
id string
key []byte
by string
consent string // the support request the owner allowed it on ("" for the Cantabile team)
until time.Time // when the owner's permission ends (zero: Cantabile team, termMax)
f *os.File
cmd *exec.Cmd
started time.Time
once sync.Once
// Under mu (review 2026-10-23: read and written from the output,
// watch and input goroutines without a lock).
mu sync.Mutex
seqIn int64
seqOut int64
last time.Time
}
// nextOut: the next output sequence number.
func (s *termSession) nextOut() int64 {
s.mu.Lock()
defer s.mu.Unlock()
s.seqOut++
return s.seqOut
}
func (s *termSession) lastInput() time.Time {
s.mu.Lock()
defer s.mu.Unlock()
return s.last
}
// input takes an input sequence number: false if not newer than the last.
func (s *termSession) input(n int64, now time.Time) bool {
s.mu.Lock()
defer s.mu.Unlock()
if n <= s.seqIn {
return false
}
s.seqIn, s.last = n, now
return true
}
type termMsg struct {
T string `json:"t"` // "term"
S string `json:"s"` // session
N int64 `json:"n"` // sequence (increasing)
D string `json:"d,omitempty"`
Cols int `json:"cols,omitempty"`
Rows int `json:"rows,omitempty"`
Close bool `json:"close,omitempty"`
MAC string `json:"mac"`
}
// termMAC: what the console signs each message with (session key).
func termMAC(key []byte, m termMsg) string {
h := hmac.New(sha256.New, key)
fmt.Fprintf(h, "%s|%d|%s|%d|%d|%t", m.S, m.N, m.D, m.Cols, m.Rows, m.Close)
return hex.EncodeToString(h.Sum(nil))
}
var (
termsMu sync.Mutex
terms = map[string]*termSession{}
)
// writeTermState: the open sessions, for the owner's panel ("Cantabile support is
// connected", End now -> SIGUSR1).
func writeTermState() {
termsMu.Lock()
list := []map[string]any{}
for _, s := range terms {
list = append(list, map[string]any{"by": s.by, "since": s.started.Unix(), "consent": s.consent})
}
termsMu.Unlock()
list = append(list, panelSessions()...) // Cantabile support in the panel (panel.go)
b, _ := json.Marshal(map[string]any{"sessions": list})
os.WriteFile(runDir+"/agent-terminal.json.tmp", b, 0o644)
os.Rename(runDir+"/agent-terminal.json.tmp", runDir+"/agent-terminal.json")
}
// closeAll: the owner pressed End now (SIGUSR1).
func (l *link) closeAll() {
termsMu.Lock()
var all []*termSession
for _, s := range terms {
all = append(all, s)
}
termsMu.Unlock()
for _, s := range all {
l.termClose(s, "ended by the owner")
}
l.closePanels()
}
func (l *link) termOpen(c command) (bool, string) {
id, keyHex := c.Args["session"], c.Args["key"]
key, err := hex.DecodeString(keyHex)
if err != nil || len(key) != 32 || id == "" {
return false, "bad session"
}
cols, _ := strconv.Atoi(c.Args["cols"])
rows, _ := strconv.Atoi(c.Args["rows"])
if cols < 20 || cols > 400 {
cols = 100
}
if rows < 5 || rows > 200 {
rows = 30
}
var until time.Time
if c.Args["consent"] != "" {
// On the owner's permission: only until it ends (sent by the console).
u, err := strconv.ParseInt(c.Args["until"], 10, 64)
if err != nil || time.Now().Unix() >= u {
return false, "the owner's permission has ended"
}
until = time.Unix(u, 0)
}
termsMu.Lock()
if _, ok := terms[id]; ok {
termsMu.Unlock()
return true, "already open"
}
termsMu.Unlock()
sh := "/bin/bash"
if _, err := os.Stat(sh); err != nil {
sh = "/bin/sh" // the recovery system: busybox
}
cmd := exec.Command(sh, "-l")
cmd.Dir = "/root"
cmd.Env = append(os.Environ(), "TERM=xterm-256color", "HOME=/root", "CANTABILE_REMOTE_BY="+c.Args["by"])
f, err := pty.StartWithSize(cmd, &pty.Winsize{Cols: uint16(cols), Rows: uint16(rows)})
if err != nil {
return false, "shell: " + err.Error()
}
s := &termSession{id: id, key: key, by: c.Args["by"], consent: c.Args["consent"], until: until, f: f, cmd: cmd, last: time.Now(), started: time.Now()}
termsMu.Lock()
terms[id] = s
termsMu.Unlock()
writeTermState()
why := "remote terminal opened by Cantabile (" + s.by + ")"
if s.consent != "" {
why += ", as you allowed in request " + s.consent
}
event("remote-terminal", why)
slog.Info("terminal open", "session", id, "by", s.by)
go l.termOutput(s)
go l.termWatch(s)
return true, "terminal open"
}
func (l *link) termOutput(s *termSession) {
buf := make([]byte, 16<<10)
for {
n, err := s.f.Read(buf)
if n > 0 {
l.publish("term", map[string]any{"s": s.id, "n": s.nextOut(), "d": base64.StdEncoding.EncodeToString(buf[:n])})
}
if err != nil {
break
}
}
l.termClose(s, "the shell ended")
}
func (l *link) termWatch(s *termSession) {
t := time.NewTicker(10 * time.Second)
defer t.Stop()
for range t.C {
termsMu.Lock()
_, open := terms[s.id]
termsMu.Unlock()
if !open {
return
}
if why := termEnd(s.started, s.lastInput(), s.until, time.Now()); why != "" {
l.termClose(s, why)
return
}
}
}
// termEnd: why a session must close now ("" while it may stay open): no
// input for 15 minutes; on the owner's permission, when it ends; otherwise
// (Cantabile team) after 1 hour.
func termEnd(started, last, until, now time.Time) string {
switch {
case now.Sub(last) > termIdle:
return "closed after 15 minutes without input"
case !until.IsZero() && !now.Before(until):
return "closed: the owner's permission ended"
case until.IsZero() && now.Sub(started) > termMax:
return "closed after 1 hour"
}
return ""
}
func (l *link) termClose(s *termSession, why string) {
s.once.Do(func() {
termsMu.Lock()
delete(terms, s.id)
termsMu.Unlock()
writeTermState()
if s.cmd.Process != nil {
s.cmd.Process.Kill()
}
s.f.Close()
s.cmd.Wait()
l.publish("term", map[string]any{"s": s.id, "n": s.nextOut(), "end": true, "why": why})
event("remote-terminal", "remote terminal closed ("+why+")")
slog.Info("terminal closed", "session", s.id, "why", why)
})
}
// termInput: a keystroke message from the console (checked with the key).
func (l *link) termInput(raw []byte) {
var m termMsg
if json.Unmarshal(raw, &m) != nil {
return
}
termsMu.Lock()
s := terms[m.S]
termsMu.Unlock()
if s == nil || !hmac.Equal([]byte(termMAC(s.key, m)), []byte(m.MAC)) || !s.input(m.N, time.Now()) {
return
}
switch {
case m.Close:
l.termClose(s, "closed by Cantabile")
case m.Cols > 0 && m.Rows > 0:
pty.Setsize(s.f, &pty.Winsize{Cols: uint16(m.Cols), Rows: uint16(m.Rows)})
case m.D != "":
if d, err := base64.StdEncoding.DecodeString(m.D); err == nil {
s.f.Write(d)
}
}
}
+82
View File
@@ -0,0 +1,82 @@
// Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.
package main
import (
"strconv"
"sync"
"testing"
"time"
)
// Sessions on the owner's permission end when it does (2 hours from the
// owner's yes), not after the Cantabile team's 1 hour.
func TestTermEnd(t *testing.T) {
t0 := time.Unix(1_800_000_000, 0)
until := t0.Add(2 * time.Hour)
for _, c := range []struct {
name string
at, last time.Time
until time.Time
wantClosing bool
}{
{"consent, 90 min in, active", t0.Add(90 * time.Minute), t0.Add(89 * time.Minute), until, false},
{"consent, at the end", until, until.Add(-time.Minute), until, true},
{"consent, idle 16 min", t0.Add(20 * time.Minute), t0.Add(4 * time.Minute), until, true},
{"Cantabile team, 59 min", t0.Add(59 * time.Minute), t0.Add(58 * time.Minute), time.Time{}, false},
{"Cantabile team, 61 min", t0.Add(61 * time.Minute), t0.Add(60 * time.Minute), time.Time{}, true},
} {
if got := termEnd(t0, c.last, c.until, c.at) != ""; got != c.wantClosing {
t.Errorf("%s: closing = %v, want %v", c.name, got, c.wantClosing)
}
}
}
// A terminal-open on a permission that has ended (or without its end) is refused.
func TestTermOpenAfterPermission(t *testing.T) {
a := &link{}
for _, until := range []string{"", "x", strconv.FormatInt(time.Now().Add(-time.Second).Unix(), 10)} {
c := command{Args: map[string]string{"session": "11111111-2222-4333-8444-555555555555",
"key": "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff", "consent": "ABCD1234", "until": until}}
if ok, msg := a.termOpen(c); ok || msg != "the owner's permission has ended" {
t.Errorf("until %q: ok=%v %q, want refused", until, ok, msg)
}
}
}
// Sequence numbers and the last input time from several goroutines (the
// output reader, the watch, the input handler): no data race (run with
// -race), every output number once, old input refused.
func TestTermSessionConcurrent(t *testing.T) {
s := &termSession{}
var wg sync.WaitGroup
seen := make(chan int64, 4000)
for i := 0; i < 4; i++ {
wg.Add(2)
go func() {
defer wg.Done()
for j := 0; j < 1000; j++ {
seen <- s.nextOut()
}
}()
go func(i int) {
defer wg.Done()
for j := 0; j < 1000; j++ {
s.input(int64(j*4+i+1), time.Now())
s.lastInput()
}
}(i)
}
wg.Wait()
close(seen)
got := map[int64]bool{}
for n := range seen {
if got[n] {
t.Fatalf("output number %d twice", n)
}
got[n] = true
}
if len(got) != 4000 || s.input(1, time.Now()) {
t.Fatalf("%d numbers; old input taken", len(got))
}
}