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

+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)
}