adds doc to new funcs, types, etc.

Author: andrewpmartinez

edge-apis/authwrapper.go

@@ -83,14 +83,22 @@ type ApiSession interface {
 
 	GetRequestHeaders() http.Header
 
+	// GetType returns the authentication method used to establish this session, enabling
+	// callers to determine whether legacy or OIDC-based authentication is in use.
 	GetType() ApiSessionType
 }
 
+// ApiSessionType identifies the authentication mechanism used to establish an API session.
 type ApiSessionType string
 
 const (
+	// ApiSessionTypeLegacy indicates a session created using the original Ziti authentication
+	// with session tokens passed in the zt-session header.
 	ApiSessionTypeLegacy ApiSessionType = "legacy"
-	ApiSessionTypeOidc   ApiSessionType = "oidc"
+
+	// ApiSessionTypeOidc indicates a session created using OpenID Connect authentication
+	// with JWT bearer tokens.
+	ApiSessionTypeOidc ApiSessionType = "oidc"
 )
 
 var _ ApiSession = (*ApiSessionLegacy)(nil)

pb/edge_client_pb/edge_client.pb.go

@@ -151,7 +151,7 @@ message PostureQuery {
   string id = 1;
   string type = 2;
   bool isPassing = 3;
-  
+
   google.protobuf.Timestamp timeoutAt = 4;
   int32 timeoutSeconds = 5;
   int32 timeoutRemainingSeconds = 6;
@@ -191,6 +191,7 @@ message PostureResponse {
 
   message TotpToken {
     string token = 1;
+    string code = 2;
   }
 
 

pb/edge_client_pb/edge_client.proto

@@ -31,14 +31,17 @@ import (
 )
 
 const (
-	// TotpAttemptDelta is the amount of time before totp expiration that new tokens are requested
+	// TotpAttemptDelta defines how far in advance of expiration the cache proactively requests
+	// new TOTP tokens, ensuring tokens remain valid during authentication flows.
 	TotpAttemptDelta = 5 * time.Minute
 
-	// TotpPostureCheckNoTimeout is the value controller posture checks use to indicate that they do not
-	// time out and require refreshed data.
+	// TotpPostureCheckNoTimeout indicates that a TOTP posture check does not expire and
+	// does not require periodic token refresh.
 	TotpPostureCheckNoTimeout = int64(-1)
 )
 
+// CacheData holds the current snapshot of device posture information including running processes,
+// network configuration, operating system details, and authentication state.
 type CacheData struct {
 	Processes    cmap.ConcurrentMap[string, ProcessInfo] // map[processPath]ProcessInfo
 	MacAddresses []string
@@ -51,6 +54,7 @@ type CacheData struct {
 	Responses    []rest_model.PostureResponseCreate
 }
 
+// NewCacheData creates an empty posture cache snapshot with initialized collections.
 func NewCacheData() *CacheData {
 	return &CacheData{
 		Processes:    cmap.New[ProcessInfo](),
@@ -64,17 +68,23 @@ func NewCacheData() *CacheData {
 	}
 }
 
+// ActiveServiceProvider supplies information about services currently in use by the client,
+// enabling the cache to determine which posture checks are relevant.
 type ActiveServiceProvider interface {
 	GetActiveDialServices() []*rest_model.ServiceDetail
 	GetActiveBindServices() []*rest_model.ServiceDetail
 }
 
+// ActiveServiceProviderFunc is a function adapter that implements ActiveServiceProvider
+// for both dial and bind service queries.
 type ActiveServiceProviderFunc func() []*rest_model.ServiceDetail
 
 func (f ActiveServiceProviderFunc) GetActiveDialServices() []*rest_model.ServiceDetail {
 	return f()
 }
 
+// Cache manages device posture data collection, tracking changes over time and coordinating
+// submission of posture responses when device state changes or policies require updates.
 type Cache struct {
 	currentData  *CacheData
 	previousData *CacheData
@@ -101,6 +111,9 @@ type Cache struct {
 	eventState  EventState
 }
 
+// NewCache creates a posture cache that monitors device state and coordinates posture response
+// submission. The cache uses the provided service provider to determine which posture checks
+// are active, the submitter to send responses, and the token provider for TOTP authentication.
 func NewCache(activeServiceProvider ActiveServiceProvider, submitter Submitter, totpTokenProvider TotpTokenProvider, closeNotify <-chan struct{}) *Cache {
 	cache := &Cache{
 		currentData:      NewCacheData(),

ziti/edge/posture/cache.go

@@ -16,14 +16,18 @@
 
 package posture
 
+// DomainProvider supplies the Windows domain name that the device is joined to,
+// used for domain membership posture checks.
 type DomainProvider interface {
 	GetDomain() string
 }
 
+// DomainFuncAsProvider converts a simple domain-returning function into a DomainProvider.
 func DomainFuncAsProvider(f func() string) DomainProvider {
 	return DomainProviderFunc(f)
 }
 
+// DomainProviderFunc is a function adapter that implements DomainProvider.
 type DomainProviderFunc func() string
 
 func (f DomainProviderFunc) GetDomain() string {

ziti/edge/posture/domain.go

@@ -2,24 +2,35 @@ package posture
 
 import "time"
 
+// WakeEvent represents a device wake event from sleep or hibernation, used to trigger
+// posture re-evaluation when the system resumes from a suspended state.
 type WakeEvent struct {
 	At time.Time
 }
 
+// UnlockEvent represents a device unlock event after screen lock, used to trigger
+// posture re-evaluation when user authentication state changes.
 type UnlockEvent struct {
 	At time.Time
 }
 
-// EventState provides the ability to listen for OS "wake" and "unlock" events. Notifications are provided
-// through channels.
+// EventState provides platform-specific monitoring of system events that may affect
+// posture compliance, such as waking from sleep or unlocking the device.
 type EventState interface {
+	// ListenForWake registers a callback for system wake events, returning a function
+	// to stop listening.
 	ListenForWake(func(WakeEvent)) (stop func(), err error)
+
+	// ListenForUnlock registers a callback for device unlock events, returning a function
+	// to stop listening.
 	ListenForUnlock(func(event UnlockEvent)) (stop func(), err error)
 }
 
 var _ EventState = (*NoOpEventState)(nil)
 
-// NoOpEventState is a stand-in implementation. Should be replaced with OS-specific implementations when available.
+// NoOpEventState is a placeholder implementation that stores callbacks without actually
+// monitoring system events. Platform-specific implementations should be used for
+// production deployments.
 type NoOpEventState struct {
 	onWake   func(WakeEvent)
 	onUnlock func(UnlockEvent)

ziti/edge/posture/eventstates.go

@@ -18,20 +18,25 @@ package posture
 
 import "net"
 
+// MacProvider supplies the list of MAC addresses for network interfaces on the device,
+// used for MAC address posture checks.
 type MacProvider interface {
 	GetMacAddresses() []string
 }
 
+// MacProviderFunc is a function adapter that implements MacProvider.
 type MacProviderFunc func() []string
 
 func (f MacProviderFunc) GetMacAddresses() []string {
 	return f()
 }
 
+// NewMacProvider creates the default MAC address provider that queries system network interfaces.
 func NewMacProvider() MacProvider {
 	return &DefaultMacProvider{}
 }
 
+// DefaultMacProvider queries the system's network interfaces to collect MAC addresses.
 type DefaultMacProvider struct{}
 
 func (p *DefaultMacProvider) GetMacAddresses() []string {

ziti/edge/posture/mac.go

@@ -24,25 +24,30 @@ import (
 	"github.com/shirou/gopsutil/v3/host"
 )
 
+// OsProvider supplies operating system type and version information for OS posture checks.
 type OsProvider interface {
 	GetOsInfo() OsInfo
 }
 
+// OsInfo contains the operating system type and semantic version.
 type OsInfo struct {
 	Type    string
 	Version string
 }
 
+// OsProviderFunc is a function adapter that implements OsProvider.
 type OsProviderFunc func() OsInfo
 
 func (f OsProviderFunc) GetOsInfo() OsInfo {
 	return f()
 }
 
+// NewOsProvider creates the default OS information provider that queries system details.
 func NewOsProvider() OsProvider {
 	return &DefaultOsProvider{}
 }
 
+// DefaultOsProvider queries platform information to determine OS type and version.
 type DefaultOsProvider struct{}
 
 func (provider DefaultOsProvider) GetOsInfo() OsInfo {

ziti/edge/posture/os.go

@@ -16,17 +16,22 @@
 
 package posture
 
+// ProcessProvider supplies information about specific processes running on the device,
+// including execution state, binary hash, and code signing details for process posture checks.
 type ProcessProvider interface {
 	GetProcessInfo(path string) ProcessInfo
 }
 
+// ProcessInfo contains details about a specific process including whether it's running,
+// its binary hash, and code signing fingerprints.
 type ProcessInfo struct {
 	IsRunning          bool
 	Hash               string
 	SignerFingerprints []string
 	QueryId            string
 }
 
+// ProcessInfoFunc is a function adapter that implements ProcessProvider.
 type ProcessInfoFunc func(path string) ProcessInfo
 
 func (f ProcessInfoFunc) GetProcessInfo(path string) ProcessInfo {

ziti/edge/posture/process.go

@@ -8,31 +8,38 @@ import (
 	"github.com/openziti/sdk-golang/ziti/edge"
 )
 
+// Submitter handles transmission of posture response data to authentication and policy
+// enforcement endpoints.
 type Submitter interface {
 	SendPostureResponse(response rest_model.PostureResponseCreate) error
 	SendPostureResponseBulk(responses []rest_model.PostureResponseCreate) error
 }
 
+// RouterConnectionProvider supplies active router connections for submitting posture data
+// directly to edge routers in high-availability deployments.
 type RouterConnectionProvider interface {
 	GetRouterConnections() []edge.RouterConn
 }
 
+// ApiSessionProvider supplies the current API session, enabling submitters to determine
+// the appropriate destination for posture responses based on authentication type.
 type ApiSessionProvider interface {
 	GetCurrentApiSession() edge_apis.ApiSession
 }
 
 var _ Submitter = (*MultiSubmitter)(nil)
 
-// MultiSubmitter submits posture responses to multiple destinations. Those destinations are determined by the
-// nature of the API Session and router connections. Legacy, non-HA, API Sessions will always send to the controller.
-// HA API Sessions will send to the controller if the router does not support posture checks. HA API Sessions must
-// send to routers that support posture checks.
+// MultiSubmitter routes posture responses to appropriate destinations based on session type
+// and router capabilities. Legacy sessions always submit to the controller, while OIDC sessions
+// submit to routers that support posture checks and fall back to the controller for older routers.
 type MultiSubmitter struct {
 	ApiSessionProvider       ApiSessionProvider
 	LegacySubmitter          Submitter
 	RouterConnectionProvider RouterConnectionProvider
 }
 
+// NewMultiSubmitter creates a submitter that intelligently routes posture responses based on
+// session authentication method and router capabilities.
 func NewMultiSubmitter(apiSessionProvider ApiSessionProvider, legacySubmitter Submitter, routerConnectionProvider RouterConnectionProvider) *MultiSubmitter {
 	return &MultiSubmitter{
 		ApiSessionProvider:       apiSessionProvider,
@@ -108,11 +115,15 @@ func filterToLegacyPostureResponses(responses []rest_model.PostureResponseCreate
 	return legacyResponse
 }
 
+// MultiDestinationError aggregates errors from posture response submission attempts
+// to multiple destinations (controller and routers), providing detailed failure information.
 type MultiDestinationError struct {
 	routerErrors    map[edge.RouterConn]error
 	controllerError error
 }
 
+// Error formats all submission failures into a comprehensive error message identifying
+// which destinations failed and why.
 func (e *MultiDestinationError) Error() string {
 	result := ""
 
@@ -148,6 +159,8 @@ func (e *MultiDestinationError) Error() string {
 	return result
 }
 
+// HasErrors returns true if any submission attempts failed, either to the controller
+// or to any routers.
 func (e *MultiDestinationError) HasErrors() bool {
 	return len(e.routerErrors) > 0 || e.controllerError != nil
 }