// 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" "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.., ctb.cmd.) 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 (/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 } // the bundles this link takes (bundles.go): as large, and as text hb["bundle_max"], hb["bundle_text"] = bundleMax, true c := consents(env("CANTABILE_CONSENT_FILE", map[bool]string{true: "/data/cantabile/edge/consent.json", false: "/data/state/consent.json"}[isHub()])) hb["consents"] = c // the site's weather cell (0.1°), for the cloud's weather: only with // the owner's share consent if c["share"] == true { if cell := siteCell(filepath.Join(l.cfg.AgentState, "site_cell.json")); cell != nil { hb["cell"] = cell } // the Hub's country and postcode (the panel's Location; tariffs, // Mieterstrom and energy sharing go by them): with the same consent if isHub() { if loc := boxLocation(boxConfig); loc != nil { hb["location"] = loc } } } return hb } // siteCell: [lat, lon] rounded to 0.1° from the agent's site_cell.json // (written from HA's configuration), or nil (none, malformed, out of range). func siteCell(path string) []float64 { var c struct{ Lat, Lon *float64 } b, err := os.ReadFile(path) if err != nil || json.Unmarshal(b, &c) != nil || c.Lat == nil || c.Lon == nil { return nil } lat, lon := math.Round(*c.Lat*10)/10, math.Round(*c.Lon*10)/10 if math.Abs(lat) > 90 || math.Abs(lon) > 180 { return nil } return []float64{lat, lon} } // 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", "market": // data bundles: checked here, read by the agent (bundles.go; flats: a building's box; acl: the devices' protection; market: the shadow market's values) 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) }