// Package bundlefiles answers one question for the "root files" verdict (R-1392, `09` §3 decision 304): do two config // bundles hold THE SAME FILES under a different label? // // WHY. The agent's config bundle (`felhom-config-bundle.json`, `11` §5.4.2) carries its own `agent_version`, so its // sha256 moves with every agent release — also when `configs/` did not change and the release (rightly) sent no bundle // job. The hub compared that one sha256, so every such release turned every box amber and, 7 days later, mailed // `os_config_bundle_behind` about files that were the vouched ones (measured 2026-11-14: 0.172.1 vs 0.173.0). // // HOW. A bundle is fetched from the package registry by its version, and it counts ONLY when the bytes hash to the // sha256 the caller already trusts (the vouched one, or the one the box reports). Then everything but the label // (`agent_version`) is hashed: the format and the whole `files` list (path, mode, check, policy, sha256, content). // // FAIL DIRECTION. Anything that cannot be read, verified or parsed answers "not the same" — the old verdict (behind, // amber, the alarm after its wait). A registry that is away never makes a box look current. package bundlefiles import ( "context" "crypto/sha256" "encoding/hex" "encoding/json" "errors" "fmt" "log" "regexp" "sync" "time" ) // Fetcher returns the published bundle file of one agent version. type Fetcher func(ctx context.Context, version string) ([]byte, error) var ( versionRE = regexp.MustCompile(`^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$`) // the builder's own rule shaRE = regexp.MustCompile(`^[0-9a-f]{64}$`) ) const ( retryAfter = 10 * time.Minute // a failed read is not asked again sooner (the System page calls this too) fetchTimeout = 5 * time.Second ) type entry struct { digest string // "" = failed at time.Time } // Resolver caches the files digest per bundle sha256. Safe for concurrent use. type Resolver struct { Fetch Fetcher Logger *log.Logger Now func() time.Time mu sync.Mutex cache map[string]entry } func (r *Resolver) now() time.Time { if r.Now != nil { return r.Now() } return time.Now() } func (r *Resolver) logf(format string, a ...any) { if r.Logger != nil { r.Logger.Printf(format, a...) } } // FilesDigest hashes a bundle's content without its label. It errors on a bundle with no `files` list. func FilesDigest(bundle []byte) (string, error) { var body map[string]any if err := json.Unmarshal(bundle, &body); err != nil { return "", fmt.Errorf("not JSON: %w", err) } files, ok := body["files"].([]any) if !ok || len(files) == 0 { return "", errors.New("no files list") } delete(body, "agent_version") canon, err := json.Marshal(body) // map keys are sorted by encoding/json if err != nil { return "", err } sum := sha256.Sum256(canon) return hex.EncodeToString(sum[:]), nil } func (r *Resolver) digest(version, sha string) string { if r == nil || r.Fetch == nil || !versionRE.MatchString(version) || !shaRE.MatchString(sha) { return "" } r.mu.Lock() if e, ok := r.cache[sha]; ok && (e.digest != "" || r.now().Sub(e.at) < retryAfter) { r.mu.Unlock() return e.digest } r.mu.Unlock() ctx, cancel := context.WithTimeout(context.Background(), fetchTimeout) defer cancel() d := "" data, err := r.Fetch(ctx, version) switch { case err != nil: r.logf("[WARN] [bundlefiles] bundle %s: cannot be read (%v) — its files are not compared", version, err) default: sum := sha256.Sum256(data) if got := hex.EncodeToString(sum[:]); got != sha { r.logf("[WARN] [bundlefiles] bundle %s: the published file is sha256 %s, expected %s — its files are not compared", version, got, sha) } else if d, err = FilesDigest(data); err != nil { r.logf("[WARN] [bundlefiles] bundle %s: %v — its files are not compared", version, err) d = "" } } r.mu.Lock() if r.cache == nil { r.cache = map[string]entry{} } r.cache[sha] = entry{digest: d, at: r.now()} r.mu.Unlock() return d } // Same reports whether the box's bundle and the vouched bundle hold the same files. Equal sha256s are the caller's // business (nothing is fetched for them); false on anything unread. func (r *Resolver) Same(boxVersion, boxSHA, vouchedVersion, vouchedSHA string) bool { if boxSHA == vouchedSHA { return boxSHA != "" } a := r.digest(vouchedVersion, vouchedSHA) if a == "" { return false } b := r.digest(boxVersion, boxSHA) same := b != "" && a == b if same { r.logf("[DEBUG] [bundlefiles] bundle %s holds the same files as the vouched %s (only the label differs)", boxVersion, vouchedVersion) } return same }