Repository Public
1/**2 * =============================================================================3 * SP BOUCHER | INFRASTRUCTURE & AUTOMATION4 * ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING5 * =============================================================================6 *7 * Project : MacLustr Command Center (MCC)8 * File : services/internal/ingest/enroll.go9 * Module : services10 * Repository : https://git.spboucher.ai/maclustr-command-center11 * Project Website : https://clustr.spboucher.ai12 * Created : 2026-11-1813 * Last Modified : 2026-11-1814 *15 * Author : Simon-Pierre Boucher16 * Position : Professor of Finance17 * Institution : Université du Québec en Outaouais (UQO)18 * Organization : SP Boucher19 * Website : https://spboucher.ai20 * Git : https://git.spboucher.ai21 *22 * Preferred Contact: admin@spboucher.ai23 * Technical Contact: dev@spboucher.ai24 * Security/Admin : admin@spboucher.ai25 *26 * Copyright (c) 202627 * Simon-Pierre Boucher28 * All rights reserved where applicable. This file is governed by the29 * applicable project license, copyright notices and relevant law.30 * Existing third-party rights and notices remain unaffected.31 *32 * License : None specified (no license file in this repository)33 *34 * Do not embed credentials, private keys, access tokens,35 * certificates or confidential personal information.36 *37 * =============================================================================38 * END OF SP BOUCHER SOURCE HEADER39 * =============================================================================40 */4142package ingest4344import (45 "context"46 "crypto/sha256"47 "encoding/base64"48 "errors"49 "fmt"50 "net/http"51 "net/netip"52 "reflect"53 "strings"54 "time"5556 "github.com/google/uuid"57 "github.com/jackc/pgx/v5"5859 "clustr.spboucher.ai/mcc/internal/audit"60 "clustr.spboucher.ai/mcc/internal/events"61 "clustr.spboucher.ai/mcc/internal/httpx"62 "clustr.spboucher.ai/mcc/internal/ids"63 "clustr.spboucher.ai/mcc/internal/pki"64 "clustr.spboucher.ai/mcc/internal/protocol"65 "clustr.spboucher.ai/mcc/internal/secret"66)6768const enrollTokenHeader = "X-MCC-Enroll-Token"6970var (71 errEnrollToken = httpx.Err(http.StatusUnauthorized, "invalid_enrollment_token", "The enrollment token is invalid, expired or already used.")72 errBadCSR = httpx.Validation("The certificate request is invalid (an ECDSA P-256 CSR in PEM is required).")73 errBadInventory = httpx.Validation("The inventory is invalid.")74 errAliasInUse = httpx.Conflict("alias_in_use", "A different machine is already registered under this alias.")75 errNodeRetired = httpx.Conflict("node_retired", "This machine was retired; restore the node before enrolling it again.")76)7778// handleEnroll exchanges a one-time token and a CSR for an agent identity.79// It is the only route reachable without a client certificate.80func (s *Server) handleEnroll(w http.ResponseWriter, r *http.Request) {81 ip := clientIP(r)82 if ok, retry := s.enrollLimiter.Allow("enroll:" + ip.String()); !ok {83 e := *httpx.ErrRateLimited84 e.RetryAfter = retry85 httpx.WriteError(w, r, &e)86 return87 }88 // Cheap shape check before any parsing or database work.89 tokenHash, err := secret.Parse(r.Header.Get(enrollTokenHeader))90 if err != nil {91 httpx.WriteError(w, r, errEnrollToken)92 return93 }94 var req protocol.EnrollRequest95 if err := decodeBody(w, r, 256<<10, &req); err != nil {96 httpx.WriteError(w, r, err)97 return98 }99 csr, err := pki.ParseCSR([]byte(req.CSRPEM))100 if err != nil {101 httpx.WriteError(w, r, errBadCSR)102 return103 }104 inv := req.Inventory105 if err := sanitizeInventory(&inv); err != nil || inv.HardwareUUID == "" {106 httpx.WriteError(w, r, errBadInventory)107 return108 }109 version := clip(req.AgentVersion, 64)110111 ctx, cancel := context.WithTimeout(r.Context(), s.reqTimeout)112 defer cancel()113114 var resp protocol.EnrollResponse115 var denied *httpx.Error116 err = s.inTx(ctx, func(tx pgx.Tx) error {117 // Atomic single use: of N concurrent presentations exactly one gets the row.118 var tokenID uuid.UUID119 var alias, kind string120 err := tx.QueryRow(ctx, `update agent_enrollment_tokens set consumed_at = now()121 where token_hash = $1 and consumed_at is null and revoked_at is null and expires_at > now()122 returning id, node_alias::text, node_kind::text`, tokenHash).Scan(&tokenID, &alias, &kind)123 if errors.Is(err, pgx.ErrNoRows) {124 denied = errEnrollToken125 return denied126 }127 if err != nil {128 return err129 }130 // One enrollment at a time per machine.131 if _, err := tx.Exec(ctx, `select pg_advisory_xact_lock(hashtextextended($1, 7731))`, "enroll:"+inv.HardwareUUID); err != nil {132 return err133 }134135 var nodeID uuid.UUID136 var nodeAlias string137 var retired *time.Time138 detail := ""139 created := false140 err = tx.QueryRow(ctx, `select id, alias::text, retired_at from nodes where hardware_uuid = $1 for update`, inv.HardwareUUID).141 Scan(&nodeID, &nodeAlias, &retired)142 switch {143 case err == nil:144 if retired != nil {145 denied = errNodeRetired146 return denied147 }148 if !strings.EqualFold(nodeAlias, alias) {149 detail = fmt.Sprintf("token issued for alias %q; hardware already registered as %q, existing node and alias kept", alias, nodeAlias)150 }151 case errors.Is(err, pgx.ErrNoRows):152 var hw *string153 err = tx.QueryRow(ctx, `select id, alias::text, hardware_uuid, retired_at from nodes where alias = $1 for update`, alias).154 Scan(&nodeID, &nodeAlias, &hw, &retired)155 switch {156 case err == nil:157 if hw != nil && *hw != "" {158 denied = errAliasInUse159 return denied160 }161 if retired != nil {162 denied = errNodeRetired163 return denied164 }165 if _, err := tx.Exec(ctx, `update nodes set hardware_uuid = $2 where id = $1`, nodeID, inv.HardwareUUID); err != nil {166 return err167 }168 detail = "adopted the manually registered node " + nodeAlias169 case errors.Is(err, pgx.ErrNoRows):170 nodeID, nodeAlias, created = ids.New(), alias, true171 nk := kind172 if inv.Kind == "mac" || inv.Kind == "linux" {173 nk = inv.Kind174 }175 if _, err := tx.Exec(ctx, `insert into nodes(id, hardware_uuid, alias, kind, registered_via) values ($1,$2,$3,$4::node_kind,'agent')`,176 nodeID, inv.HardwareUUID, alias, nk); err != nil {177 return err178 }179 detail = "node created"180 default:181 return err182 }183 default:184 return err185 }186187 // Re-enrollment: the previous identity of this node stops working now.188 tag, err := tx.Exec(ctx, `update agents set revoked_at = now(), revoked_reason = 're-enrolled' where node_id = $1 and revoked_at is null`, nodeID)189 if err != nil {190 return err191 }192 if tag.RowsAffected() > 0 {193 detail = strings.TrimPrefix(detail+"; previous agent revoked (re-enrollment)", "; ")194 }195196 agentID := ids.New()197 now := time.Now().UTC()198 certPEM, cert, err := s.ca.SignAgent(csr, agentID, now)199 if err != nil {200 return err201 }202 fp := sha256.Sum256(cert.Raw)203 if _, err := tx.Exec(ctx, `insert into agents(id, node_id, cert_serial, cert_fingerprint, cert_not_after, version, os, last_seen_at)204 values ($1,$2,$3,$4,$5,$6,$7, now())`,205 agentID, nodeID, pki.SerialString(cert.SerialNumber), fp[:], cert.NotAfter, version, inv.Kind); err != nil {206 return err207 }208 if _, err := applyInventory(ctx, tx, nodeID, &inv); err != nil {209 return err210 }211 if _, err := tx.Exec(ctx, `update nodes set last_seen_at = now() where id = $1`, nodeID); err != nil {212 return err213 }214 keys, err := commandKeys(ctx, tx)215 if err != nil {216 return err217 }218 var ipp *netip.Addr219 if ip.IsValid() {220 ipp = &ip221 }222 if _, err := audit.Append(ctx, tx, audit.Entry{223 ActorKind: "agent", ActorID: &agentID, ActorLabel: nodeAlias, IP: ipp,224 Action: "agent.enrolled", TargetKind: "node", TargetID: nodeID.String(),225 Params: map[string]any{226 "alias": nodeAlias, "token_alias": alias, "enrollment_id": tokenID.String(), "node_created": created,227 "agent_version": version, "cert_serial": pki.SerialString(cert.SerialNumber),228 "cert_not_after": cert.NotAfter.UTC().Format(time.RFC3339), "model": inv.Model, "os_version": inv.OSVersion,229 },230 Outcome: audit.Success, Detail: detail, CorrelationID: httpx.Correlation(r.Context()),231 }); err != nil {232 return err233 }234 if err := events.Publish(ctx, tx, "node.updated", map[string]any{"node_id": nodeID, "reason": "agent_enrolled"}); err != nil {235 return err236 }237 resp = protocol.EnrollResponse{238 AgentID: agentID.String(), NodeID: nodeID.String(), CertPEM: string(certPEM), CAPEM: string(s.ca.PEM),239 CommandKeys: keys, Endpoints: s.cfg.IngestAdvertise, ServerName: s.cfg.IngestServerName, IntervalS: s.intervalS,240 }241 return nil242 })243 if err != nil {244 if denied != nil {245 // Refusals are audited outside the rolled-back transaction, best effort.246 s.auditEnrollDenied(r, ip, denied, inv.HardwareUUID)247 }248 s.writeErr(w, r, err)249 return250 }251 s.forgetAuth()252 s.log.Info("ingest: agent enrolled", "agent_id", resp.AgentID, "node_id", resp.NodeID, "ip", ip.String())253 writeJSON(w, http.StatusOK, resp)254}255256func (s *Server) auditEnrollDenied(r *http.Request, ip netip.Addr, reason *httpx.Error, hw string) {257 ctx, cancel := context.WithTimeout(context.WithoutCancel(r.Context()), 5*time.Second)258 defer cancel()259 var ipp *netip.Addr260 if ip.IsValid() {261 ipp = &ip262 }263 if _, err := audit.Append(ctx, s.pool, audit.Entry{264 ActorKind: "agent", ActorLabel: "unenrolled", IP: ipp, Action: "agent.enroll_denied",265 Params: map[string]any{"reason": reason.Code, "hardware_uuid": hw},266 Outcome: audit.Denied, Detail: reason.Message, CorrelationID: httpx.Correlation(r.Context()),267 }); err != nil {268 s.log.Warn("ingest: could not audit enrollment refusal", "err", err)269 }270}271272// commandKeys returns the active command verification keys (public material).273func commandKeys(ctx context.Context, q interface {274 Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)275}) (map[string]string, error) {276 rows, err := q.Query(ctx, `select key_id, public_key from command_keys where retired_at is null`)277 if err != nil {278 return nil, err279 }280 defer rows.Close()281 out := map[string]string{}282 for rows.Next() {283 var id string284 var pub []byte285 if err := rows.Scan(&id, &pub); err != nil {286 return nil, err287 }288 out[id] = base64.StdEncoding.EncodeToString(pub)289 }290 return out, rows.Err()291}292293// handleRenew issues a new certificate for the same agent from a new CSR.294// The previous certificate stays valid for a short overlap so a lost response295// cannot lock the agent out.296func (s *Server) handleRenew(w http.ResponseWriter, r *http.Request) {297 a := agentFrom(r.Context())298 var req protocol.RenewRequest299 if err := decodeBody(w, r, 64<<10, &req); err != nil {300 httpx.WriteError(w, r, err)301 return302 }303 csr, err := pki.ParseCSR([]byte(req.CSRPEM))304 if err != nil {305 httpx.WriteError(w, r, errBadCSR)306 return307 }308 ctx, cancel := context.WithTimeout(r.Context(), s.reqTimeout)309 defer cancel()310 now := time.Now().UTC()311 certPEM, cert, err := s.ca.SignAgent(csr, a.ID, now)312 if err != nil {313 s.writeErr(w, r, err)314 return315 }316 leaf := leafFrom(r.Context())317 presented := pki.SerialString(leaf.SerialNumber)318 fp := sha256.Sum256(cert.Raw)319 var resp protocol.RenewResponse320 err = s.inTx(ctx, func(tx pgx.Tx) error {321 // The overlap is granted to the certificate that asked for the renewal.322 tag, err := tx.Exec(ctx, `update agents set323 prev_cert_serial = $2,324 prev_cert_valid_until = least(now() + interval '24 hours', $3::timestamptz),325 cert_serial = $4, cert_fingerprint = $5, cert_not_after = $6326 where id = $1 and revoked_at is null`,327 a.ID, presented, leaf.NotAfter, pki.SerialString(cert.SerialNumber), fp[:], cert.NotAfter)328 if err != nil {329 return err330 }331 if tag.RowsAffected() == 0 {332 return errAgentRevoked333 }334 keys, err := commandKeys(ctx, tx)335 if err != nil {336 return err337 }338 ip := clientIP(r)339 var ipp *netip.Addr340 if ip.IsValid() {341 ipp = &ip342 }343 if _, err := audit.Append(ctx, tx, audit.Entry{344 ActorKind: "agent", ActorID: &a.ID, IP: ipp, Action: "agent.cert_renewed",345 TargetKind: "node", TargetID: a.NodeID.String(),346 Params: map[string]any{"cert_serial": pki.SerialString(cert.SerialNumber), "previous_serial": presented,347 "cert_not_after": cert.NotAfter.UTC().Format(time.RFC3339)},348 Outcome: audit.Success, CorrelationID: httpx.Correlation(r.Context()),349 }); err != nil {350 return err351 }352 resp = protocol.RenewResponse{CertPEM: string(certPEM), CAPEM: string(s.ca.PEM), CommandKeys: keys}353 return nil354 })355 if err != nil {356 s.writeErr(w, r, err)357 return358 }359 s.forgetAuth()360 writeJSON(w, http.StatusOK, resp)361}362363// ─────────────────────────── inventory ───────────────────────────364365func clip(s string, n int) string {366 s = strings.ToValidUTF8(strings.TrimSpace(s), "")367 s = strings.Map(func(r rune) rune {368 if r < 0x20 || r == 0x7f {369 return -1370 }371 return r372 }, s)373 if len(s) > n {374 s = s[:n]375 s = strings.ToValidUTF8(s, "")376 }377 return s378}379380// sanitizeInventory bounds every field an agent controls.381func sanitizeInventory(inv *protocol.Inventory) error {382 inv.HardwareUUID = clip(inv.HardwareUUID, 64)383 if strings.ContainsAny(inv.HardwareUUID, " /\\") {384 return errors.New("hardware uuid")385 }386 inv.Hostname, inv.Model, inv.Chip, inv.Arch = clip(inv.Hostname, 128), clip(inv.Model, 64), clip(inv.Chip, 96), clip(inv.Arch, 16)387 inv.GPUModel, inv.OSName, inv.OSVersion = clip(inv.GPUModel, 96), clip(inv.OSName, 32), clip(inv.OSVersion, 32)388 inv.OSBuild, inv.Kernel = clip(inv.OSBuild, 32), clip(inv.Kernel, 96)389 if inv.Kind != "mac" && inv.Kind != "linux" {390 return errors.New("kind")391 }392 if inv.CPUCores < 0 || inv.CPUCores > 4096 || inv.GPUCores < 0 || inv.GPUCores > 4096 || inv.MemBytes < 0 || inv.StorageBytes < 0 {393 return errors.New("counts")394 }395 if len(inv.CPULevels) > 8 || len(inv.Interfaces) > 32 || len(inv.Managers) > 8 {396 return errors.New("too many items")397 }398 for i := range inv.CPULevels {399 inv.CPULevels[i].Name = clip(inv.CPULevels[i].Name, 32)400 if inv.CPULevels[i].Cores < 0 || inv.CPULevels[i].Cores > 4096 {401 return errors.New("cpu level")402 }403 }404 for i := range inv.Interfaces {405 it := &inv.Interfaces[i]406 it.Name, it.Kind, it.MAC, it.Media = clip(it.Name, 32), clip(it.Kind, 16), clip(it.MAC, 32), clip(it.Media, 96)407 if len(it.Addrs) > 16 {408 it.Addrs = it.Addrs[:16]409 }410 for j := range it.Addrs {411 it.Addrs[j] = clip(it.Addrs[j], 64)412 }413 }414 for i := range inv.Managers {415 inv.Managers[i] = clip(inv.Managers[i], 16)416 }417 return nil418}419420// primaryIP picks the address of the default-route interface (IPv4 first).421func primaryIP(inv *protocol.Inventory) *string {422 pick := func(onlyDefault bool) *string {423 for _, want4 := range []bool{true, false} {424 for _, it := range inv.Interfaces {425 if !it.Up || (onlyDefault && !it.Default) || it.Kind == "tunnel" && !it.Default {426 continue427 }428 for _, a := range it.Addrs {429 p, err := netip.ParsePrefix(a)430 var ad netip.Addr431 if err == nil {432 ad = p.Addr()433 } else if ad, err = netip.ParseAddr(a); err != nil {434 continue435 }436 if ad.IsLoopback() || ad.IsLinkLocalUnicast() || ad.Is4() != want4 {437 continue438 }439 s := ad.String()440 return &s441 }442 }443 }444 return nil445 }446 if p := pick(true); p != nil {447 return p448 }449 return pick(false)450}451452// applyInventory stores an inventory on the node and reports whether it453// differs from the stored one.454func applyInventory(ctx context.Context, tx pgx.Tx, nodeID uuid.UUID, inv *protocol.Inventory) (changed bool, err error) {455 var prev *protocol.Inventory456 var prevAt *time.Time457 if err := tx.QueryRow(ctx, `select case when inventory_at is null then null else inventory end, inventory_at from nodes where id = $1 for update`, nodeID).458 Scan(&prev, &prevAt); err != nil {459 return false, err460 }461 changed = prev == nil || !reflect.DeepEqual(normalizeInv(*prev), normalizeInv(*inv))462 levels := inv.CPULevels463 if levels == nil {464 levels = []protocol.CPULevel{}465 }466 _, err = tx.Exec(ctx, `update nodes set467 hostname = $2, model = nullif($3,''), chip = nullif($4,''), arch = nullif($5,''),468 cpu_cores = nullif($6,0), cpu_levels = $7, gpu_cores = nullif($8,0),469 mem_bytes = nullif($9::bigint,0), storage_bytes = nullif($10::bigint,0),470 os_name = nullif($11,''), os_version = nullif($12,''), os_build = nullif($13,''),471 primary_ip = coalesce($14::inet, primary_ip), kind = $15::node_kind,472 inventory = $16, inventory_at = now()473 where id = $1`,474 nodeID, inv.Hostname, inv.Model, inv.Chip, inv.Arch, inv.CPUCores, mustJSON(levels), inv.GPUCores,475 inv.MemBytes, inv.StorageBytes, inv.OSName, inv.OSVersion, inv.OSBuild, primaryIP(inv), inv.Kind, mustJSON(inv))476 return changed, err477}478479func normalizeInv(i protocol.Inventory) protocol.Inventory {480 i.BootTime = i.BootTime.UTC().Truncate(time.Minute)481 if len(i.CPULevels) == 0 {482 i.CPULevels = nil483 }484 if len(i.Interfaces) == 0 {485 i.Interfaces = nil486 }487 if len(i.Managers) == 0 {488 i.Managers = nil489 }490 for k := range i.Interfaces {491 if len(i.Interfaces[k].Addrs) == 0 {492 i.Interfaces[k].Addrs = nil493 }494 }495 return i496}497