Documentation
¶
Overview ¶
Package fleetagentuc is the use-case layer for fleet agent identity (#409, epic #405): an operator mints a single-use enrolment token; an agent exchanges it for a long-lived bearer credential; the API authenticates every subsequent call by that credential. Secret material is generated and hashed here; only hashes reach the store, and the plaintext is returned once.
Index ¶
- Variables
- type EnrolInput
- type HeartbeatInput
- type Service
- func (s *Service) Authenticate(ctx context.Context, token string) (*fleetagent.Agent, error)
- func (s *Service) AuthenticateCertificate(ctx context.Context, tenantID, agentID shared.ID, fingerprint string) (*fleetagent.Agent, error)
- func (s *Service) Decommission(ctx context.Context, agent *fleetagent.Agent) error
- func (s *Service) Enrol(ctx context.Context, enrolToken string, in EnrolInput) (*fleetagent.Agent, string, []byte, error)
- func (s *Service) Heartbeat(ctx context.Context, agent *fleetagent.Agent, in HeartbeatInput) error
- func (s *Service) ListAgents(ctx context.Context, tenantID shared.ID) ([]*fleetagent.Agent, error)
- func (s *Service) MintEnrolToken(ctx context.Context, actor string, tenantID shared.ID, ttl time.Duration) (string, error)
- func (s *Service) Revoke(ctx context.Context, actor string, tenantID, id shared.ID, reason string) error
- func (s *Service) SetCA(ca ports.CertificateIssuer)
- func (s *Service) SetWorkOrders(store ports.WorkOrderStore)
Constants ¶
This section is empty.
Variables ¶
var ( ErrUnauthenticated = errors.New("fleetagent: unauthenticated") ErrRevoked = errors.New("fleetagent: agent revoked") // ErrDecommissioned means the agent cleanly uninstalled and reported itself decommissioned (#412); // its credential no longer authenticates. Mapped to 403 at the adapter edge, like ErrRevoked. ErrDecommissioned = errors.New("fleetagent: agent decommissioned") )
ErrUnauthenticated means the presented credential is missing, malformed, unknown, or its secret does not match. ErrRevoked means the agent exists but has been revoked. Both are mapped to HTTP at the adapter edge (401 / 403).
Functions ¶
This section is empty.
Types ¶
type EnrolInput ¶
type EnrolInput struct {
Name string
Platform string
OSVersion string
AgentVersion string
Capabilities []string
// CSRPEM is an optional PEM certificate signing request. When present and a CA is configured,
// the control plane issues a client certificate and records its fingerprint; the returned
// certificate PEM is the agent's cryptographic identity for mutual-TLS auth (#408).
CSRPEM []byte
}
EnrolInput describes the enrolling agent.
type HeartbeatInput ¶
type HeartbeatInput struct {
Platform string
OSVersion string
AgentVersion string
Capabilities []string
}
HeartbeatInput carries the liveness-report fields.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the fleet agent identity use case.
func NewService ¶
func NewService(store ports.FleetAgentStore, audit ports.AuditLogger, clock ports.Clock, ids ports.IDGenerator) (*Service, error)
NewService validates its dependencies and returns the service.
func (*Service) Authenticate ¶
Authenticate resolves and verifies an agent bearer credential. It returns ErrUnauthenticated for any missing/malformed/unknown credential or secret mismatch, and ErrRevoked for a revoked agent.
func (*Service) AuthenticateCertificate ¶
func (s *Service) AuthenticateCertificate(ctx context.Context, tenantID, agentID shared.ID, fingerprint string) (*fleetagent.Agent, error)
AuthenticateCertificate resolves and verifies an agent by its client-certificate identity (tenant and agent id read from the verified certificate subject, plus the certificate fingerprint). It returns ErrUnauthenticated for an unknown agent, an agent with no certificate, or a fingerprint mismatch, and ErrRevoked for a revoked agent. The fingerprint comparison is constant time.
func (*Service) Decommission ¶
Decommission marks an agent cleanly removed on the agent's own authenticated report during uninstall (#412), cancels its in-flight work orders, and audits it. It is self-reported: the actor is the agent's own id. A revoked agent is unaffected (an operator revocation is the stronger terminal state). The control plane then shows the identity as decommissioned rather than letting it decay into stale. Tenant scope comes from the authenticated agent, never from the request body.
func (*Service) Enrol ¶
func (s *Service) Enrol(ctx context.Context, enrolToken string, in EnrolInput) (*fleetagent.Agent, string, []byte, error)
Enrol exchanges a valid enrolment token for a new agent identity and returns its bearer credential once. The tenant is taken from the enrolment token, never from the caller.
func (*Service) Heartbeat ¶
func (s *Service) Heartbeat(ctx context.Context, agent *fleetagent.Agent, in HeartbeatInput) error
Heartbeat records liveness and refreshes the agent's reported attributes.
func (*Service) ListAgents ¶
ListAgents returns the tenant's agents.
func (*Service) MintEnrolToken ¶
func (s *Service) MintEnrolToken(ctx context.Context, actor string, tenantID shared.ID, ttl time.Duration) (string, error)
MintEnrolToken issues a single-use enrolment token for tenantID valid for ttl, and returns the plaintext once. Only its hash is stored. This is an operator action (RBAC-gated at the adapter).
func (*Service) Revoke ¶
func (s *Service) Revoke(ctx context.Context, actor string, tenantID, id shared.ID, reason string) error
Revoke marks an agent revoked (so its bearer token and certificate no longer authenticate) with operator attribution and a reason, and cancels the agent's in-flight work orders.
func (*Service) SetCA ¶
func (s *Service) SetCA(ca ports.CertificateIssuer)
SetCA wires the control-plane certificate issuer, enabling CSR-based certificate identity.
func (*Service) SetWorkOrders ¶
func (s *Service) SetWorkOrders(store ports.WorkOrderStore)
SetWorkOrders wires the work order store so revoking an agent cancels its in-flight orders.
Source Files