remoteaccess

package
v1.5.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Overview

Package remoteaccess provides provider-neutral session plumbing for agent-routed interactive access. Protocol adapters such as SSH or Proxmox console own target-specific dialing; Manager owns session frame routing.

Index

Constants

View Source
const (
	ProtocolProxmoxConsole = "proxmox_console"
	ProtocolVSphereConsole = "vsphere_console"
	ProtocolRDP            = "rdp"
	ProtocolApp            = "app"
	ProtocolTCP            = "tcp"
	ProtocolDatabase       = "database"
	ProtocolKubernetes     = "kubernetes"
	ProtocolDesktop        = "desktop"
	ProtocolOT             = "ot"
)
View Source
const (
	FrameTypeApplicationOpen             = "app_open"
	FrameTypeApplicationRequest          = "app_request"
	FrameTypeApplicationResponseMetadata = "app_response_metadata"
	FrameTypeApplicationData             = "app_data"
	FrameTypeApplicationProgress         = "app_progress"
	FrameTypeApplicationClose            = "app_close"
	FrameTypeApplicationError            = "app_error"
	FrameTypeApplicationOutcome          = "app_outcome"

	FrameTypeTCPOpen     = "tcp_open"
	FrameTypeTCPData     = "tcp_data"
	FrameTypeTCPProgress = "tcp_progress"
	FrameTypeTCPClose    = "tcp_close"
	FrameTypeTCPError    = "tcp_error"
	FrameTypeTCPOutcome  = "tcp_outcome"

	ApplicationSchemeHTTP  ApplicationScheme = "http"
	ApplicationSchemeHTTPS ApplicationScheme = "https"

	ApplicationDataDirectionRequest  ApplicationDataDirection = "request"
	ApplicationDataDirectionResponse ApplicationDataDirection = "response"
	TCPDataDirectionClient           TCPDataDirection         = "client"
	TCPDataDirectionUpstream         TCPDataDirection         = "upstream"

	ApplicationStatusStarted        RemoteAccessStreamStatus = "started"
	ApplicationStatusInProgress     RemoteAccessStreamStatus = "in_progress"
	ApplicationStatusCompleted      RemoteAccessStreamStatus = "completed"
	ApplicationStatusDenied         RemoteAccessStreamStatus = "denied"
	ApplicationStatusFailed         RemoteAccessStreamStatus = "failed"
	ApplicationStatusQuotaExhausted RemoteAccessStreamStatus = "quota_exhausted"
	ApplicationStatusClosed         RemoteAccessStreamStatus = "closed"

	TCPStatusStarted        RemoteAccessStreamStatus = ApplicationStatusStarted
	TCPStatusInProgress     RemoteAccessStreamStatus = ApplicationStatusInProgress
	TCPStatusCompleted      RemoteAccessStreamStatus = ApplicationStatusCompleted
	TCPStatusDenied         RemoteAccessStreamStatus = ApplicationStatusDenied
	TCPStatusFailed         RemoteAccessStreamStatus = ApplicationStatusFailed
	TCPStatusQuotaExhausted RemoteAccessStreamStatus = ApplicationStatusQuotaExhausted
	TCPStatusClosed         RemoteAccessStreamStatus = ApplicationStatusClosed
)
View Source
const (
	DesktopCredentialModeDomainDelegation = "domain_delegation"
	DesktopCredentialModeMemoryUser       = "memory_user"
	DesktopCredentialModeSmartCard        = "smart_card"
	DesktopCredentialModeBrokeredSecret   = "brokered_secret"

	DesktopTLSModeVerify     = "verify"
	DesktopTLSModePinnedCA   = "pinned_ca"
	DesktopTLSModeInsecure   = "insecure"
	DesktopTLSModeSystem     = "system"
	DesktopTLSModeTOFU       = "tofu"
	DesktopDefaultTLSPolicy  = DesktopTLSModeVerify
	DesktopNLAModeRequired   = "required"
	DesktopNLAModeDisabled   = "disabled"
	DesktopDefaultNLAPolicy  = DesktopNLAModeRequired
	DesktopDefaultRDPPort    = 3389
	DesktopDefaultMaxWidth   = 1920
	DesktopDefaultMaxHeight  = 1080
	DesktopDefaultFrameRate  = 30
	DesktopDefaultBitrateBPS = 8_000_000
	DesktopDefaultIdleSec    = 900
	DesktopDefaultTTLSec     = 3600
	DesktopMaxCABundlePEM    = 256 * 1024
	DesktopMaxWidth          = 7680
	DesktopMaxHeight         = 4320
	DesktopMaxFrameRate      = 60
	DesktopMaxBitrateBPS     = 100_000_000
	DesktopMaxFrameData      = 1_048_576
	DesktopMaxInputTokenSize = 128
	DesktopMaxAuditReason    = 256

	DesktopClipboardModeDisabled      = "disabled"
	DesktopClipboardModeTextToRemote  = "text_to_remote"
	DesktopClipboardModeTextToBrowser = "text_to_browser"
	DesktopClipboardModeTextBoth      = "text_bidirectional"

	DesktopFrameTypeUpdate     = "desktop.update"
	DesktopFrameTypeInput      = "desktop.input"
	DesktopFrameTypeResize     = "desktop.resize"
	DesktopFrameTypeClipboard  = "desktop.clipboard"
	DesktopFrameTypeQuality    = "desktop.quality"
	DesktopFrameTypeDisconnect = "desktop.disconnect"

	DesktopLifecycleEventOpen    = "desktop.session.open"
	DesktopLifecycleEventReady   = "desktop.session.ready"
	DesktopLifecycleEventClose   = "desktop.session.close"
	DesktopLifecycleEventError   = "desktop.session.error"
	DesktopLifecycleEventRevoked = "desktop.session.revoked"

	DesktopInputKindKey     = "key"
	DesktopInputKindPointer = "pointer"
	DesktopInputKindFocus   = "focus"

	DesktopClipboardDirectionToRemote  = "to_remote"
	DesktopClipboardDirectionToBrowser = "to_browser"
)
View Source
const (
	DefaultRDPAdapterBinary      = "serviceradar-rdp-adapter"
	RDPAdapterCapabilitiesArg    = "--capabilities"
	RDPAdapterCapabilitiesSchema = "serviceradar.rdp.helper.capabilities.v1"
	RDPAdapterProbeTimeout       = 5 * time.Second
	RDPAdapterMinProtocolVersion = 1
)
View Source
const (
	DesktopMediaMagic          = "SRDP"
	DesktopMediaVersion        = 1
	DesktopMediaHeaderSize     = 48
	DesktopMediaMaxMetadata    = 64 * 1024
	DesktopMediaMaxCloseReason = 256

	DesktopMediaFlagKeyframe      uint8 = 0x01
	DesktopMediaFlagFullFrame     uint8 = 0x02
	DesktopMediaFlagCursorUpdate  uint8 = 0x04
	DesktopMediaFlagEndOfStream   uint8 = 0x08
	DesktopMediaFlagDiscontinuity uint8 = 0x10
	DesktopMediaAllowedFlags            = DesktopMediaFlagKeyframe |
		DesktopMediaFlagFullFrame |
		DesktopMediaFlagCursorUpdate |
		DesktopMediaFlagEndOfStream |
		DesktopMediaFlagDiscontinuity

	DesktopMediaPayloadVideo     = "video"
	DesktopMediaPayloadDirtyRect = "dirty_rect"
	DesktopMediaPayloadTile      = "tile"
	DesktopMediaPayloadCursor    = "cursor"
	DesktopMediaPayloadMetadata  = "metadata"
	DesktopMediaControlTypeAck   = "desktop_media_ack"
	DesktopMediaQualityAuto      = "auto"
	DesktopMediaQualityLow       = "low"

	DesktopMediaDefaultInitialCreditBytes = 4 * 1024 * 1024
	DesktopMediaDefaultMaxChunkBytes      = 256 * 1024
	DesktopMediaDefaultMaxAckCreditBytes  = 4 * 1024 * 1024
)
View Source
const (
	CapabilityRemoteAccess          = "remote_access"
	CapabilityRemoteAccessSSH       = "remote_access.ssh"
	CapabilityRemoteAccessApp       = "remote_access.app"
	CapabilityRemoteAccessTCP       = "remote_access.tcp"
	CapabilityRemoteAccessFile      = "remote_access.file_transfer"
	CapabilityRemoteAccessSFTP      = "remote_access.sftp"
	CapabilityRemoteAccessDesktop   = "remote_access.desktop"
	CapabilityRemoteAccessRDP       = "remote_access.rdp"
	CapabilityRemoteAccessRecording = "remote_access.recording"
	CapabilityRemoteAccessBPF       = "remote_access.bpf"
)
View Source
const (
	FrameTypeEnhancedEvent = "enhanced_event"

	EnhancedEventCommand = "command"
	EnhancedEventFile    = "file"
	EnhancedEventNetwork = "network"
	EnhancedEventLoss    = "loss"
)
View Source
const (
	ProtocolSFTP = "sftp"

	FrameTypeFileTransferRequest  = "file_transfer_request"
	FrameTypeFileTransferProgress = "file_transfer_progress"
	FrameTypeFileTransferData     = "file_transfer_data"
	FrameTypeFileTransferAck      = "file_transfer_ack"
	FrameTypeFileTransferError    = "file_transfer_error"
	FrameTypeFileTransferOutcome  = "file_transfer_outcome"

	FileTransferOperationList     FileTransferOperation = "list"
	FileTransferOperationStat     FileTransferOperation = "stat"
	FileTransferOperationDownload FileTransferOperation = "download"
	FileTransferOperationUpload   FileTransferOperation = "upload"
	FileTransferOperationMkdir    FileTransferOperation = "mkdir"
	FileTransferOperationRename   FileTransferOperation = "rename"
	FileTransferOperationRemove   FileTransferOperation = "remove"
	FileTransferOperationChmod    FileTransferOperation = "chmod"
	FileTransferOperationChown    FileTransferOperation = "chown"

	FileTransferDirectionRead   FileTransferDirection = "read"
	FileTransferDirectionWrite  FileTransferDirection = "write"
	FileTransferDirectionManage FileTransferDirection = "manage"

	FileTransferStatusRequested       FileTransferStatus = "requested"
	FileTransferStatusStarted         FileTransferStatus = "started"
	FileTransferStatusInProgress      FileTransferStatus = "in_progress"
	FileTransferStatusCompleted       FileTransferStatus = "completed"
	FileTransferStatusDenied          FileTransferStatus = "denied"
	FileTransferStatusFailed          FileTransferStatus = "failed"
	FileTransferStatusCanceled        FileTransferStatus = "canceled"
	FileTransferStatusQuotaExhausted  FileTransferStatus = "quota_exhausted"
	FileTransferStatusApprovalPending FileTransferStatus = "approval_pending"
)
View Source
const (
	FrameTypeOpen      = "open"
	FrameTypeReady     = "ready"
	FrameTypeData      = "data"
	FrameTypeResize    = "resize"
	FrameTypeHeartbeat = "heartbeat"
	FrameTypeClose     = "close"
	FrameTypeError     = "error"
	FrameTypeOutcome   = "outcome"

	MaxTerminalCols      = 500
	MaxTerminalRows      = 200
	MaxTerminalFrameData = 65_536
	MaxOpenFrameData     = 262_144
)
View Source
const (
	ProtocolSSH = "ssh"

	SSHCredentialModeUserPresent    = "user_present"
	SSHCredentialModeSSHCertificate = "ssh_certificate"
)
View Source
const (
	EnhancedExecutionManagedTarget = "managed_target"
)
View Source
const (
	FrameAuthAlgorithm = "hmac-sha256-v1"
)

Variables

View Source
var (
	ErrInvalidApplicationTargetID      = errors.New("invalid application target id")
	ErrInvalidApplicationSessionID     = errors.New("invalid application session id")
	ErrInvalidApplicationScheme        = errors.New("invalid application scheme")
	ErrInvalidApplicationUpstreamHost  = errors.New("invalid application upstream host")
	ErrInvalidApplicationUpstreamPort  = errors.New("invalid application upstream port")
	ErrInvalidApplicationRequestID     = errors.New("invalid application request id")
	ErrInvalidApplicationMethod        = errors.New("invalid application method")
	ErrInvalidApplicationPath          = errors.New("invalid application path")
	ErrInvalidApplicationDataDirection = errors.New("invalid application data direction")
	ErrInvalidApplicationSequence      = errors.New("invalid application sequence")
	ErrInvalidApplicationStatus        = errors.New("invalid application status")

	ErrInvalidTCPTargetID      = errors.New("invalid tcp target id")
	ErrInvalidTCPSessionID     = errors.New("invalid tcp session id")
	ErrInvalidTCPConnectionID  = errors.New("invalid tcp connection id")
	ErrInvalidTCPUpstreamHost  = errors.New("invalid tcp upstream host")
	ErrInvalidTCPUpstreamPort  = errors.New("invalid tcp upstream port")
	ErrInvalidTCPDataDirection = errors.New("invalid tcp data direction")
	ErrInvalidTCPSequence      = errors.New("invalid tcp sequence")
	ErrInvalidTCPStatus        = errors.New("invalid tcp status")
)
View Source
var (
	ErrApplicationMethodNotAllowed = errors.New("application method not allowed")
	ErrApplicationPathNotAllowed   = errors.New("application path not allowed")
	ErrApplicationRequestTooLarge  = errors.New("application request body exceeds quota")
	ErrApplicationResponseTooLarge = errors.New("application response body exceeds quota")
	ErrApplicationAdapterNil       = errors.New("application http adapter is nil")
	ErrApplicationSessionMismatch  = errors.New("application request session does not match open session")
)
View Source
var (
	ErrInvalidDesktopTarget  = errors.New("invalid desktop target")
	ErrInvalidDesktopFrame   = errors.New("invalid desktop frame")
	ErrDesktopContentRecord  = errors.New("desktop content recording disabled")
	ErrDesktopQuotaExceeded  = errors.New("desktop quota exceeded")
	ErrDesktopSessionExpired = errors.New("desktop session expired")
	ErrDesktopRouteLost      = errors.New("desktop route lost")
)
View Source
var (
	ErrDesktopAdapterUnavailable = errors.New("desktop adapter unavailable")
	ErrDesktopAdapterClosed      = errors.New("desktop adapter closed")
)
View Source
var (
	ErrInvalidDesktopMediaFrame = errors.New("invalid desktop media frame")
	ErrInvalidDesktopMediaAck   = errors.New("invalid desktop media ack")
	ErrDesktopMediaNoCredit     = errors.New("desktop media credit exhausted")
)
View Source
var (
	ErrInvalidFileTransferID          = errors.New("invalid file transfer id")
	ErrInvalidFileTransferSessionID   = errors.New("invalid file transfer session id")
	ErrInvalidFileTransferOperation   = errors.New("invalid file transfer operation")
	ErrInvalidFileTransferDirection   = errors.New("invalid file transfer direction")
	ErrInvalidFileTransferPath        = errors.New("invalid file transfer path")
	ErrFileTransferDestinationMissing = errors.New("file transfer destination path is required")
	ErrInvalidFileTransferSequence    = errors.New("invalid file transfer sequence")
	ErrInvalidFileTransferOffset      = errors.New("invalid file transfer offset")
)
View Source
var (
	ErrFileTransferPolicyDenied       = errors.New("file transfer denied by policy")
	ErrFileTransferPolicyUnavailable  = errors.New("file transfer policy is unavailable")
	ErrInvalidFileTransferPathRule    = errors.New("invalid file transfer path rule")
	ErrInvalidFileTransferSymlinkMode = errors.New("invalid file transfer symlink mode")
	ErrFileTransferApprovalRequired   = errors.New("file transfer approval is required")
	ErrFileTransferQuotaExceeded      = errors.New("file transfer quota exceeded")
)
View Source
var (
	ErrInvalidFrameAuth     = errors.New("invalid remote access frame auth")
	ErrUnsupportedFrameAuth = errors.New("unsupported remote access frame auth")
)
View Source
var (
	ErrAdapterUnavailable = errors.New("remote access adapter unavailable")
	ErrSessionExists      = errors.New("remote access session is already active")
	ErrSessionNotActive   = errors.New("remote access session is not active")
	ErrUnsupportedFrame   = errors.New("unsupported remote access frame type")
	ErrInvalidFrameSize   = errors.New("invalid remote access frame size")
)
View Source
var (
	ErrSFTPInputRequired                = errors.New("sftp input is required")
	ErrSFTPInputEmpty                   = errors.New("sftp upload file must not be empty")
	ErrSFTPOutputRequired               = errors.New("sftp output is required")
	ErrSFTPOperationMetadataRequired    = errors.New("sftp operation metadata is required")
	ErrSFTPDirectionOperationMismatch   = errors.New("sftp direction does not match operation")
	ErrUnsupportedFileTransferOperation = errors.New("unsupported file transfer operation")
)
View Source
var (
	ErrMissingSSHTargetHost            = errors.New("missing SSH target host")
	ErrInvalidSSHTargetPort            = errors.New("invalid SSH target port")
	ErrInvalidSSHFieldSize             = errors.New("invalid SSH field size")
	ErrSSHUsernameRequired             = errors.New("ssh username is required")
	ErrSSHCredentialRequired           = errors.New("ssh private key or password is required")
	ErrSSHCertificateRequiresKey       = errors.New("ssh certificate requires matching private key")
	ErrSSHCertificateKeyMismatch       = errors.New("ssh certificate public key does not match private key")
	ErrInvalidSSHCertificate           = errors.New("invalid ssh certificate")
	ErrSSHHostKeyStoreUnavailable      = errors.New("SSH host key verification store is not available to the agent connector")
	ErrUnsupportedSSHHostKeyPolicy     = errors.New("unsupported ssh_host_key_policy")
	ErrSSHSessionOutputChannelOverflow = errors.New("ssh session output channel overflow")
)
View Source
var (
	// ErrSSHHostKeyUnknown reports that no entry exists yet for the target in
	// the agent-local known-hosts store. The operator can review the offered
	// fingerprint and enroll it with the trust-on-first-use policy.
	ErrSSHHostKeyUnknown = errors.New("ssh host key is not trusted")

	// ErrSSHHostKeyMismatch reports that the target offered a key that differs
	// from the one already pinned for it or from an explicit retry approval.
	ErrSSHHostKeyMismatch = errors.New("ssh host key does not match the trusted entry")
)

Host-key verification failures reach the operator as a session close reason, which is the only channel the console frame vocabulary offers. The two classes below therefore carry a stable, documented sentence shape so the browser can tell an enrollable first contact apart from a key that changed under a host that was already trusted. Only the first is ever offered for acceptance; the second is the man-in-the-middle case and stays a hard close.

View Source
var (
	ErrUnsupportedSSHProtocol       = errors.New("unsupported remote access ssh protocol")
	ErrInvalidSSHOpenPayload        = errors.New("invalid ssh open payload")
	ErrUnsupportedSSHCredentialMode = errors.New("unsupported ssh credential mode")
	ErrSSHCertificateRequired       = errors.New("ssh certificate is required")
	ErrSSHOpenSessionMismatch       = errors.New("ssh open payload session_id does not match frame")
	ErrSSHOpenProtocolMismatch      = errors.New("ssh open payload protocol does not match frame")
	ErrSSHOpenAgentMismatch         = errors.New("ssh open payload agent_id does not match frame metadata")
	ErrSSHOpenGatewayMismatch       = errors.New("ssh open payload gateway_id does not match frame metadata")
)
View Source
var (
	ErrTCPAdapterNil            = errors.New("tcp adapter is nil")
	ErrTCPDirectionNotAllowed   = errors.New("tcp frame direction not allowed")
	ErrTCPBytesInQuotaExceeded  = errors.New("tcp bytes in quota exceeded")
	ErrTCPBytesOutQuotaExceeded = errors.New("tcp bytes out quota exceeded")
	ErrTCPAdapterClosed         = errors.New("tcp adapter is closed")
	ErrInvalidTCPReadChunkSize  = errors.New("invalid tcp read chunk size")
	ErrTCPSessionMismatch       = errors.New("tcp frame binding does not match open connection")
	ErrTCPSequenceOutOfOrder    = errors.New("tcp frame sequence is not greater than the previous client frame")
)
View Source
var ErrEnhancedRecordingTargetBoundaryRequired = errors.New("target-side enhanced recording requires managed target execution")
View Source
var ErrEnhancedRecordingUnavailable = errors.New("enhanced recording unavailable")
View Source
var ErrUnsupportedProtocolAdapter = errors.New("unsupported remote access protocol adapter")

Functions

func DesktopAuditMetadata added in v1.2.69

func DesktopAuditMetadata(payload DesktopOpenPayload) map[string]string

DesktopAuditMetadata returns metadata that is safe to persist for desktop session audit/recording records. It intentionally omits usernames, passwords, credential secret references, and caller-supplied metadata maps.

func DesktopFrameAuditMetadata added in v1.2.69

func DesktopFrameAuditMetadata(frame DesktopFrame) map[string]string

DesktopFrameAuditMetadata returns frame metadata suitable for audit and recording records without retaining screen pixels, clipboard data, key names, button names, or other frame payload contents.

func DesktopLifecycleAuditMetadata added in v1.2.69

func DesktopLifecycleAuditMetadata(
	payload DesktopOpenPayload,
	eventType string,
	timestampUnix int64,
	outcome string,
) (map[string]string, error)

DesktopLifecycleAuditMetadata returns safe metadata for desktop session lifecycle records. It includes target/policy posture plus a fixed event type and capped single-line outcome, but it omits credential material and caller-supplied metadata.

func DesktopTerminationAuditMetadata added in v1.2.69

func DesktopTerminationAuditMetadata(frame DesktopFrame) map[string]string

DesktopTerminationAuditMetadata returns safe metadata for desktop close/error outcomes. It includes a capped, single-line reason while keeping generic frame audit metadata free of close reasons by default.

func DialSSHClient added in v1.2.60

func DialSSHClient(ctx context.Context, cfg SSHConfig) (*ssh.Client, error)

DialSSHClient opens a real SSH client using the same credential custody and host-key trust path as SSH PTY sessions. Non-PTY protocols such as SFTP must use this instead of creating their own x/crypto/ssh client configuration.

func EncodeDesktopFramePayload added in v1.2.69

func EncodeDesktopFramePayload(frame DesktopFrame, policy DesktopScreenPolicy) ([]byte, error)

EncodeDesktopFramePayload validates and serializes a typed desktop frame for transport inside the existing ConsoleFrame data field.

func EncodeDesktopFramePayloadWithPolicy added in v1.2.69

func EncodeDesktopFramePayloadWithPolicy(
	frame DesktopFrame,
	policy DesktopScreenPolicy,
	redirection DesktopRedirectionPolicy,
) ([]byte, error)

EncodeDesktopFramePayloadWithPolicy validates and serializes a typed desktop frame with an explicit redirection policy.

func EncodeDesktopMediaFrame added in v1.2.69

func EncodeDesktopMediaFrame(frame DesktopMediaFrame, policy DesktopScreenPolicy) ([]byte, error)

func NormalizeRDPAdapterPath added in v1.2.69

func NormalizeRDPAdapterPath(path string) string

NormalizeRDPAdapterPath returns the configured helper path, or the default helper binary name when the agent config leaves the path unset.

func PlatformEnhancedRecordingAvailable

func PlatformEnhancedRecordingAvailable() bool

PlatformEnhancedRecordingAvailable reports whether this host has a ServiceRadar-owned BPF collector that can satisfy required BPF policies. The procfs collector returned by NewPlatformEnhancedRecorder is an optional/fallback collector and must not advertise the BPF capability.

func RDPAdapterBinaryAvailable added in v1.2.69

func RDPAdapterBinaryAvailable(path string) bool

func RDPAdapterReady added in v1.2.69

func RDPAdapterReady(path string) bool

func ResolveRDPAdapterPath added in v1.2.69

func ResolveRDPAdapterPath(path string) (string, error)

ResolveRDPAdapterPath resolves the local per-session RDP helper that backs the concrete IronRDP adapter. Agents must not advertise remote_access.rdp unless this helper can be executed.

func ValidateDesktopContentRecording added in v1.2.69

func ValidateDesktopContentRecording(frame DesktopFrame, policy DesktopRecordingPolicy) error

ValidateDesktopContentRecording returns nil only when policy explicitly allows retaining the content represented by the frame.

func ValidateDesktopFrame added in v1.2.69

func ValidateDesktopFrame(frame DesktopFrame, policy DesktopScreenPolicy) error

func ValidateDesktopFrameWithPolicy added in v1.2.69

func ValidateDesktopFrameWithPolicy(
	frame DesktopFrame,
	policy DesktopScreenPolicy,
	redirection DesktopRedirectionPolicy,
) error

ValidateDesktopFrameWithPolicy validates a desktop frame against both screen and redirection policy. Use this for any path that accepts clipboard or other local resource redirection frames.

func ValidateDesktopMediaAck added in v1.2.69

func ValidateDesktopMediaAck(ack DesktopMediaAck, sessionBindingID, mediaSessionID string) error

func ValidateDesktopMediaFrame added in v1.2.69

func ValidateDesktopMediaFrame(frame DesktopMediaFrame, policy DesktopScreenPolicy) error

func ValidateDesktopRouteBinding added in v1.2.69

func ValidateDesktopRouteBinding(target DesktopTarget, localAgentID string, currentGatewayID string) error

ValidateDesktopRouteBinding verifies that a still-running desktop session is on the selected agent and, when supplied, selected gateway route.

func ValidateDesktopSessionLifetime added in v1.2.69

func ValidateDesktopSessionLifetime(
	policy DesktopScreenPolicy,
	startUnix int64,
	lastActivityUnix int64,
	nowUnix int64,
) error

ValidateDesktopSessionLifetime enforces the idle and absolute TTL policy for an adapter session. Timestamps are Unix seconds; callers should update lastActivityUnix whenever user input, screen traffic, or explicit heartbeat activity is accepted for the session.

Types

type AdapterRegistry

type AdapterRegistry struct {
	// contains filtered or unexported fields
}

AdapterRegistry resolves protocol names to protocol-specific PTY openers. It is intentionally credential-agnostic; each adapter receives only the session-scoped open frame and must enforce its own payload validation.

func DefaultAdapterRegistry

func DefaultAdapterRegistry(sshOptions SSHOpenOptions) *AdapterRegistry

DefaultAdapterRegistry returns the protocols that are implemented today.

func NewAdapterRegistry

func NewAdapterRegistry() *AdapterRegistry

NewAdapterRegistry creates an empty adapter registry.

func (*AdapterRegistry) Open

func (r *AdapterRegistry) Open(ctx context.Context, frame Frame) (PTY, error)

Open opens the adapter selected by the frame protocol.

func (*AdapterRegistry) Opener

func (r *AdapterRegistry) Opener() Opener

Opener returns a manager-compatible opener that dispatches by Frame.Protocol.

func (*AdapterRegistry) Register

func (r *AdapterRegistry) Register(protocol string, opener Opener)

Register adds or replaces a protocol opener. Empty protocols and nil openers are ignored to keep callers from accidentally registering a catch-all.

type ApplicationClosePayload added in v1.2.67

type ApplicationClosePayload struct {
	RequestID string `json:"request_id,omitempty"`
	SessionID string `json:"session_id"`
	Reason    string `json:"reason,omitempty"`
}

ApplicationClosePayload reports an orderly application request or session close.

func (ApplicationClosePayload) Validate added in v1.2.67

func (p ApplicationClosePayload) Validate() error

type ApplicationDataDirection added in v1.2.67

type ApplicationDataDirection string

ApplicationDataDirection marks whether bounded bytes flow toward the application upstream or back toward the browser.

func (ApplicationDataDirection) Valid added in v1.2.67

func (d ApplicationDataDirection) Valid() bool

Valid returns true when the application data direction is part of the frame contract.

type ApplicationDataPayload added in v1.2.67

type ApplicationDataPayload struct {
	RequestID string                   `json:"request_id"`
	SessionID string                   `json:"session_id"`
	Direction ApplicationDataDirection `json:"direction"`
	Sequence  uint64                   `json:"sequence"`
	Data      []byte                   `json:"data,omitempty"`
	EOF       bool                     `json:"eof,omitempty"`
}

ApplicationDataPayload carries one bounded request or response body chunk.

func (ApplicationDataPayload) Validate added in v1.2.67

func (p ApplicationDataPayload) Validate() error

type ApplicationErrorPayload added in v1.2.67

type ApplicationErrorPayload struct {
	RequestID string                   `json:"request_id,omitempty"`
	SessionID string                   `json:"session_id"`
	Status    RemoteAccessStreamStatus `json:"status"`
	Code      string                   `json:"code"`
	Message   string                   `json:"message,omitempty"`
}

ApplicationErrorPayload reports a denied, failed, or quota-exhausted application action.

func (ApplicationErrorPayload) Validate added in v1.2.67

func (p ApplicationErrorPayload) Validate() error

type ApplicationHTTPAdapter added in v1.2.67

type ApplicationHTTPAdapter struct {
	// contains filtered or unexported fields
}

func NewApplicationHTTPAdapter added in v1.2.67

func NewApplicationHTTPAdapter(open ApplicationOpenPayload, opts ApplicationHTTPAdapterOptions) (*ApplicationHTTPAdapter, error)

func (*ApplicationHTTPAdapter) Close added in v1.2.67

func (a *ApplicationHTTPAdapter) Close()

func (*ApplicationHTTPAdapter) Execute added in v1.2.67

func (*ApplicationHTTPAdapter) MaxRequestBodyBytes added in v1.2.67

func (a *ApplicationHTTPAdapter) MaxRequestBodyBytes() int64

type ApplicationHTTPAdapterOptions added in v1.2.67

type ApplicationHTTPAdapterOptions struct {
	RootCAs     *x509.CertPool
	DialContext func(context.Context, string, string) (net.Conn, error)
	Timeout     time.Duration
}

type ApplicationHTTPResult added in v1.2.67

type ApplicationHTTPResult struct {
	Metadata ApplicationResponseMetadataPayload
	Data     ApplicationDataPayload
	Progress ApplicationProgressPayload
	Outcome  ApplicationOutcomePayload
}

type ApplicationOpenPayload added in v1.2.67

type ApplicationOpenPayload struct {
	TargetID                string            `json:"target_id"`
	SessionID               string            `json:"session_id"`
	Scheme                  ApplicationScheme `json:"scheme"`
	UpstreamHost            string            `json:"upstream_host"`
	UpstreamPort            int               `json:"upstream_port"`
	HostHeader              string            `json:"host_header,omitempty"`
	SNI                     string            `json:"sni,omitempty"`
	TLSPolicy               map[string]any    `json:"tls_policy,omitempty"`
	CABundleRef             string            `json:"ca_bundle_ref,omitempty"`
	AllowedMethods          []string          `json:"allowed_methods,omitempty"`
	AllowedPathPrefixes     []string          `json:"allowed_path_prefixes,omitempty"`
	HeaderPolicy            map[string]any    `json:"header_policy,omitempty"`
	CookiePolicy            map[string]any    `json:"cookie_policy,omitempty"`
	QuotaPolicy             map[string]any    `json:"quota_policy,omitempty"`
	ApprovalID              string            `json:"approval_id,omitempty"`
	RecordingPolicy         map[string]any    `json:"recording_policy,omitempty"`
	EnhancedRecordingPolicy map[string]any    `json:"enhanced_recording_policy,omitempty"`
	Metadata                map[string]string `json:"metadata,omitempty"`
}

ApplicationOpenPayload is carried by FrameTypeApplicationOpen after the control plane has resolved a registered target. It is never accepted directly from browser intent.

func (ApplicationOpenPayload) Validate added in v1.2.67

func (p ApplicationOpenPayload) Validate() error

type ApplicationOutcomePayload added in v1.2.67

type ApplicationOutcomePayload struct {
	SessionID     string                   `json:"session_id"`
	TargetID      string                   `json:"target_id"`
	Status        RemoteAccessStreamStatus `json:"status"`
	RequestCount  int64                    `json:"request_count,omitempty"`
	RequestBytes  int64                    `json:"request_bytes,omitempty"`
	ResponseBytes int64                    `json:"response_bytes,omitempty"`
	FailureReason string                   `json:"failure_reason,omitempty"`
}

ApplicationOutcomePayload reports durable metadata for audit and replay.

func (ApplicationOutcomePayload) Validate added in v1.2.67

func (p ApplicationOutcomePayload) Validate() error

type ApplicationProgressPayload added in v1.2.67

type ApplicationProgressPayload struct {
	RequestID     string                   `json:"request_id,omitempty"`
	SessionID     string                   `json:"session_id"`
	Status        RemoteAccessStreamStatus `json:"status"`
	RequestBytes  int64                    `json:"request_bytes,omitempty"`
	ResponseBytes int64                    `json:"response_bytes,omitempty"`
}

ApplicationProgressPayload reports lifecycle and byte-count metadata.

func (ApplicationProgressPayload) Validate added in v1.2.67

func (p ApplicationProgressPayload) Validate() error

type ApplicationRequestPayload added in v1.2.67

type ApplicationRequestPayload struct {
	RequestID string              `json:"request_id"`
	SessionID string              `json:"session_id"`
	Method    string              `json:"method"`
	Path      string              `json:"path"`
	Query     string              `json:"query,omitempty"`
	Headers   map[string][]string `json:"headers,omitempty"`
}

ApplicationRequestPayload carries request metadata only. Request bodies use FrameTypeApplicationData and must stay bounded by adapter quota policy.

func (ApplicationRequestPayload) Validate added in v1.2.67

func (p ApplicationRequestPayload) Validate() error

type ApplicationResponseMetadataPayload added in v1.2.67

type ApplicationResponseMetadataPayload struct {
	RequestID   string              `json:"request_id"`
	SessionID   string              `json:"session_id"`
	StatusCode  int                 `json:"status_code"`
	Headers     map[string][]string `json:"headers,omitempty"`
	ContentType string              `json:"content_type,omitempty"`
}

ApplicationResponseMetadataPayload carries response headers and status without body bytes.

func (ApplicationResponseMetadataPayload) Validate added in v1.2.67

type ApplicationScheme added in v1.2.67

type ApplicationScheme string

ApplicationScheme identifies the trusted upstream scheme selected from target policy.

func (ApplicationScheme) Valid added in v1.2.67

func (s ApplicationScheme) Valid() bool

Valid returns true when the application upstream scheme is supported.

type DesktopAdapterInput added in v1.2.69

type DesktopAdapterInput interface {
	SendDesktopFrame(context.Context, DesktopFrame) error
}

DesktopAdapterInput receives browser control/input frames after the session guard has validated route, lifetime, redirection, and quota policy.

type DesktopAdapterOpenRequest added in v1.2.69

type DesktopAdapterOpenRequest struct {
	SessionID        string
	ActorID          string
	LocalAgentID     string
	CurrentGatewayID string
	StartUnix        int64
	Target           DesktopTarget
	CredentialGrant  *DesktopCredentialGrant
	MediaSender      DesktopMediaSender
}

type DesktopAdapterRuntime added in v1.2.69

type DesktopAdapterRuntime struct {
	LocalAgentID     string
	CurrentGatewayID string
	NowUnix          func() int64
	NowUnixNano      func() int64
	Adapter          DesktopRDPAdapter
}

DesktopAdapterRuntime validates a trusted desktop open frame and delegates to a concrete protocol adapter. It intentionally keeps validation outside the adapter implementation so every adapter enters through the same policy path.

func (DesktopAdapterRuntime) OpenRDP added in v1.2.69

func (r DesktopAdapterRuntime) OpenRDP(
	ctx context.Context,
	frame Frame,
	mediaSender DesktopMediaSender,
) (DesktopAdapterSession, error)

type DesktopAdapterSession added in v1.2.69

type DesktopAdapterSession interface {
	DesktopAdapterInput
	Close(context.Context, string) error
}

DesktopAdapterSession is an active protocol adapter instance. It owns the target connection and must release any per-session credential material during Close.

type DesktopCredentialGrant added in v1.2.69

type DesktopCredentialGrant struct {
	Mode                string `json:"mode"`
	Username            string `json:"username,omitempty"`
	Password            string `json:"password,omitempty"`
	CredentialSecretRef string `json:"credential_secret_ref,omitempty"`
	ActorID             string `json:"actor_id,omitempty"`
	SessionID           string `json:"session_id,omitempty"`
	TargetID            string `json:"target_id,omitempty"`
	RouteID             string `json:"route_id,omitempty"`
	ExpiresUnix         int64  `json:"expires_unix,omitempty"`
}

func NormalizeDesktopCredentialGrant added in v1.2.69

func NormalizeDesktopCredentialGrant(
	grant DesktopCredentialGrant,
	target DesktopTarget,
) (DesktopCredentialGrant, error)

func NormalizeDesktopCredentialGrantAt added in v1.2.69

func NormalizeDesktopCredentialGrantAt(
	grant DesktopCredentialGrant,
	target DesktopTarget,
	nowUnix int64,
) (DesktopCredentialGrant, error)

NormalizeDesktopCredentialGrantAt validates a desktop credential grant at a caller-provided Unix timestamp. Tests and adapters with trusted clocks can use this to make brokered-secret TTL decisions explicit.

func ValidateDesktopOpenCredentialGrant added in v1.2.69

func ValidateDesktopOpenCredentialGrant(
	payload DesktopOpenPayload,
	sessionID string,
	nowUnix int64,
) (*DesktopCredentialGrant, error)

ValidateDesktopOpenCredentialGrant normalizes a desktop open-frame credential grant and enforces session binding for credential modes that carry secrets.

func (*DesktopCredentialGrant) DropSensitive added in v1.2.69

func (grant *DesktopCredentialGrant) DropSensitive()

DropSensitive clears session credential material from the grant once an adapter no longer needs it. Password is string-backed because grants arrive over JSON, so this releases references rather than promising allocator-level memory scrubbing.

type DesktopCredentialPolicy added in v1.2.69

type DesktopCredentialPolicy struct {
	Mode                string   `json:"mode"`
	AllowedPrincipals   []string `json:"allowed_principals,omitempty"`
	CredentialSecretRef string   `json:"credential_secret_ref,omitempty"`
}

type DesktopFrame added in v1.2.69

type DesktopFrame struct {
	SessionID string             `json:"session_id"`
	Protocol  string             `json:"protocol"`
	FrameType string             `json:"frame_type"`
	Width     uint32             `json:"width,omitempty"`
	Height    uint32             `json:"height,omitempty"`
	Encoding  string             `json:"encoding,omitempty"`
	Data      []byte             `json:"data,omitempty"`
	Input     *DesktopInputEvent `json:"input,omitempty"`
	Quality   *DesktopQuality    `json:"quality,omitempty"`
	Direction string             `json:"direction,omitempty"`
	Reason    string             `json:"reason,omitempty"`
	Timestamp int64              `json:"timestamp,omitempty"`
	Metadata  map[string]string  `json:"metadata,omitempty"`
}

DesktopFrame is the protocol-neutral graphical frame contract used by RDP and future desktop adapters. It is intentionally separate from terminal PTY byte frames.

func DecodeDesktopFramePayload added in v1.2.69

func DecodeDesktopFramePayload(data []byte, policy DesktopScreenPolicy) (DesktopFrame, error)

DecodeDesktopFramePayload decodes and validates a typed desktop frame carried inside the existing ConsoleFrame data field.

func DecodeDesktopFramePayloadForSession added in v1.2.69

func DecodeDesktopFramePayloadForSession(
	data []byte,
	policy DesktopScreenPolicy,
	sessionID string,
) (DesktopFrame, error)

DecodeDesktopFramePayloadForSession decodes a typed desktop frame and rejects frames that are not bound to the expected remote-access session.

func DecodeDesktopFramePayloadForSessionWithPolicy added in v1.2.69

func DecodeDesktopFramePayloadForSessionWithPolicy(
	data []byte,
	policy DesktopScreenPolicy,
	redirection DesktopRedirectionPolicy,
	sessionID string,
) (DesktopFrame, error)

DecodeDesktopFramePayloadForSessionWithPolicy decodes a typed desktop frame, applies redirection policy, and rejects frames not bound to the expected remote-access session.

func DecodeDesktopFramePayloadWithPolicy added in v1.2.69

func DecodeDesktopFramePayloadWithPolicy(
	data []byte,
	policy DesktopScreenPolicy,
	redirection DesktopRedirectionPolicy,
) (DesktopFrame, error)

DecodeDesktopFramePayloadWithPolicy decodes and validates a typed desktop frame with an explicit redirection policy.

type DesktopFrameQuotaWindow added in v1.2.69

type DesktopFrameQuotaWindow struct {
	// contains filtered or unexported fields
}

DesktopFrameQuotaWindow tracks per-second screen update quotas for adapter code before the dedicated desktop media stream carries production traffic.

func NewDesktopFrameQuotaWindow added in v1.2.69

func NewDesktopFrameQuotaWindow(policy DesktopScreenPolicy) DesktopFrameQuotaWindow

func (*DesktopFrameQuotaWindow) Consume added in v1.2.69

func (w *DesktopFrameQuotaWindow) Consume(frame DesktopFrame, nowUnixNano int64) error

Consume applies frame-rate and bitrate quotas to desktop update frames. Non-screen frames are ignored here and still use their normal validators.

type DesktopInputEvent added in v1.2.69

type DesktopInputEvent struct {
	Kind    string `json:"kind"`
	Key     string `json:"key,omitempty"`
	Down    bool   `json:"down,omitempty"`
	Button  string `json:"button,omitempty"`
	X       uint32 `json:"x,omitempty"`
	Y       uint32 `json:"y,omitempty"`
	Focused bool   `json:"focused,omitempty"`
}

type DesktopMediaAck added in v1.2.69

type DesktopMediaAck struct {
	SessionBindingID string `json:"session_binding_id"`
	MediaSessionID   string `json:"media_session_id"`
	LastAcceptedSeq  uint64 `json:"last_accepted_seq"`
	CreditBytes      uint64 `json:"credit_bytes"`
	QualityLevel     string `json:"quality_level,omitempty"`
	Pause            bool   `json:"pause,omitempty"`
	Resume           bool   `json:"resume,omitempty"`
	CloseReason      string `json:"close_reason,omitempty"`
}

func DecodeDesktopMediaAckMessage added in v1.2.69

func DecodeDesktopMediaAckMessage(data []byte, sessionBindingID, mediaSessionID string) (DesktopMediaAck, error)

type DesktopMediaAckHandler added in v1.2.69

type DesktopMediaAckHandler func(context.Context, DesktopMediaAck) error

type DesktopMediaAckHandlerRegistrar added in v1.2.69

type DesktopMediaAckHandlerRegistrar interface {
	SetDesktopMediaAckHandler(DesktopMediaAckHandler)
}

DesktopMediaAckHandlerRegistrar lets adapter-facing media sinks route browser/gateway backpressure acknowledgements back to protocol adapters.

type DesktopMediaCreditWindow added in v1.2.69

type DesktopMediaCreditWindow struct {
	// contains filtered or unexported fields
}

func NewDesktopMediaCreditWindow added in v1.2.69

func NewDesktopMediaCreditWindow(initialCreditBytes uint64, maxChunkBytes uint32) (DesktopMediaCreditWindow, error)

func (*DesktopMediaCreditWindow) Adjust added in v1.2.69

func (w *DesktopMediaCreditWindow) Adjust(creditBytes uint64)

func (*DesktopMediaCreditWindow) ApplyAck added in v1.2.69

func (w *DesktopMediaCreditWindow) ApplyAck(ack DesktopMediaAck, sessionBindingID, mediaSessionID string) error

func (DesktopMediaCreditWindow) CanSend added in v1.2.69

func (DesktopMediaCreditWindow) CloseReason added in v1.2.69

func (w DesktopMediaCreditWindow) CloseReason() string

func (*DesktopMediaCreditWindow) Consume added in v1.2.69

func (DesktopMediaCreditWindow) LastAcceptedSeq added in v1.2.69

func (w DesktopMediaCreditWindow) LastAcceptedSeq() (uint64, bool)

func (DesktopMediaCreditWindow) MaxAckCreditBytes added in v1.2.69

func (w DesktopMediaCreditWindow) MaxAckCreditBytes() uint64

func (DesktopMediaCreditWindow) MaxChunkBytes added in v1.2.69

func (w DesktopMediaCreditWindow) MaxChunkBytes() uint32

func (DesktopMediaCreditWindow) Paused added in v1.2.69

func (w DesktopMediaCreditWindow) Paused() bool

func (DesktopMediaCreditWindow) QualityLevel added in v1.2.69

func (w DesktopMediaCreditWindow) QualityLevel() string

func (DesktopMediaCreditWindow) RemainingBytes added in v1.2.69

func (w DesktopMediaCreditWindow) RemainingBytes() uint64

type DesktopMediaFrame added in v1.2.69

type DesktopMediaFrame struct {
	SessionBindingID  string
	MediaSessionID    string
	Sequence          uint64
	TimestampUnixNano int64
	Width             uint32
	Height            uint32
	PayloadFamily     string
	Encoding          string
	Metadata          []byte
	Payload           []byte
	Flags             uint8
}

DesktopMediaFrame is the compact binary envelope shared by the Go agent, gateway/core, and browser worker. It matches web-ng's SRDP browser parser.

func DecodeDesktopMediaFrame added in v1.2.69

func DecodeDesktopMediaFrame(data []byte, policy DesktopScreenPolicy) (DesktopMediaFrame, error)

func DecodeDesktopMediaFrameView added in v1.2.69

func DecodeDesktopMediaFrameView(data []byte, policy DesktopScreenPolicy) (DesktopMediaFrame, error)

DecodeDesktopMediaFrameView decodes a frame without copying metadata or payload. Callers must keep data alive and immutable for as long as the returned frame is used.

type DesktopMediaFrameParts added in v1.2.69

type DesktopMediaFrameParts struct {
	Header           []byte
	SessionBindingID []byte
	MediaSessionID   []byte
	Encoding         []byte
	Metadata         []byte
	Payload          []byte
}

DesktopMediaFrameParts exposes the SRDP frame as ordered byte slices for vectored writes. Header can be caller-owned and reused across frames; Metadata and Payload alias the frame input and must remain immutable until the write completes.

func BuildDesktopMediaFrameParts added in v1.2.69

func BuildDesktopMediaFrameParts(
	frame DesktopMediaFrame,
	policy DesktopScreenPolicy,
	header []byte,
) (DesktopMediaFrameParts, error)

func BuildDesktopMediaFramePartsWithStaticFields added in v1.2.69

func BuildDesktopMediaFramePartsWithStaticFields(
	frame DesktopMediaFrame,
	policy DesktopScreenPolicy,
	header []byte,
	staticFields DesktopMediaFrameStaticFields,
) (DesktopMediaFrameParts, error)

func (DesktopMediaFrameParts) AppendTo added in v1.2.69

func (p DesktopMediaFrameParts) AppendTo(dst []byte) []byte

func (DesktopMediaFrameParts) Len added in v1.2.69

func (p DesktopMediaFrameParts) Len() int

type DesktopMediaFrameStaticFields added in v1.2.69

type DesktopMediaFrameStaticFields struct {
	SessionBindingID string
	MediaSessionID   string
	Encoding         string
	// contains filtered or unexported fields
}

DesktopMediaFrameStaticFields stores per-session frame fields in both string and byte form so high-volume media loops can avoid re-encoding stable values for every screen update.

func NewDesktopMediaFrameStaticFields added in v1.2.69

func NewDesktopMediaFrameStaticFields(
	sessionBindingID,
	mediaSessionID,
	encoding string,
) (DesktopMediaFrameStaticFields, error)

type DesktopMediaSender added in v1.2.69

type DesktopMediaSender interface {
	SendDesktopMediaFrame(context.Context, DesktopMediaFrame) error
}

DesktopMediaSender is the adapter-facing media sink for SRDP screen updates. Implementations typically wrap the dedicated desktop media gRPC stream. Metadata and Payload may alias adapter-owned buffers; senders must synchronously serialize or copy bytes needed after SendDesktopMediaFrame returns and must not retain the frame slices.

type DesktopOpenPayload added in v1.2.69

type DesktopOpenPayload struct {
	Schema          string                  `json:"schema,omitempty"`
	ActorID         string                  `json:"actor_id,omitempty"`
	Target          DesktopTarget           `json:"target"`
	CredentialGrant *DesktopCredentialGrant `json:"credential_grant,omitempty"`
	Metadata        map[string]string       `json:"metadata,omitempty"`
}

DesktopOpenPayload is the agent-side open-frame contract for graphical desktop protocols. It contains trusted target policy compiled by core, not browser-selected upstream settings.

func DecodeDesktopOpenFrameForAgent added in v1.2.69

func DecodeDesktopOpenFrameForAgent(frame Frame, localAgentID string) (DesktopOpenPayload, error)

DecodeDesktopOpenFrameForAgent decodes a trusted desktop open frame and enforces that the selected route is bound to the local agent before an adapter dials the target.

func DecodeDesktopOpenPayload added in v1.2.69

func DecodeDesktopOpenPayload(data []byte) (DesktopOpenPayload, error)

DecodeDesktopOpenPayload decodes and validates a trusted desktop open-frame payload before an agent adapter dials the target.

type DesktopQuality added in v1.2.69

type DesktopQuality struct {
	MaxFrameRate uint32 `json:"max_frame_rate,omitempty"`
	MaxBitrate   uint32 `json:"max_bitrate_bps,omitempty"`
	Width        uint32 `json:"width,omitempty"`
	Height       uint32 `json:"height,omitempty"`
}

type DesktopRDPAdapter added in v1.2.69

type DesktopRDPAdapter interface {
	Open(context.Context, DesktopAdapterOpenRequest) (DesktopAdapterSession, error)
}

DesktopRDPAdapter is the narrow seam for the future IronRDP bridge. Open receives an already-normalized, route-bound target and memory-only credential grant. Implementations must not persist credential material.

type DesktopRecordingPolicy added in v1.2.69

type DesktopRecordingPolicy struct {
	MetadataEnabled  bool `json:"metadata_enabled"`
	ScreenEnabled    bool `json:"screen_enabled,omitempty"`
	ClipboardEnabled bool `json:"clipboard_enabled,omitempty"`
	FileEnabled      bool `json:"file_enabled,omitempty"`
	AudioEnabled     bool `json:"audio_enabled,omitempty"`
}

type DesktopRedirectionPolicy added in v1.2.69

type DesktopRedirectionPolicy struct {
	ClipboardMode string `json:"clipboard_mode"`
	Drive         bool   `json:"drive,omitempty"`
	Printer       bool   `json:"printer,omitempty"`
	Audio         bool   `json:"audio,omitempty"`
	SmartCard     bool   `json:"smart_card,omitempty"`
	FileCopy      bool   `json:"file_copy,omitempty"`
}

type DesktopRoute added in v1.2.69

type DesktopRoute struct {
	SelectedAgentID string   `json:"selected_agent_id"`
	SelectedGateway string   `json:"selected_gateway_id,omitempty"`
	AllowedAgentIDs []string `json:"allowed_agent_ids,omitempty"`
}

type DesktopScreenPolicy added in v1.2.69

type DesktopScreenPolicy struct {
	MaxWidth    uint32 `json:"max_width"`
	MaxHeight   uint32 `json:"max_height"`
	ColorDepth  uint32 `json:"color_depth,omitempty"`
	FrameRate   uint32 `json:"frame_rate"`
	BitrateBPS  uint32 `json:"bitrate_bps"`
	IdleSeconds uint32 `json:"idle_seconds"`
	TTLSeconds  uint32 `json:"ttl_seconds"`
}

type DesktopSessionGuard added in v1.2.69

type DesktopSessionGuard struct {
	// contains filtered or unexported fields
}

DesktopSessionGuard centralizes the per-frame checks an adapter must perform while a desktop session is active. It keeps route binding, lifetime, redirection policy, and update-frame quotas on one path so adapter code does not accidentally validate only part of the session contract.

func NewDesktopSessionGuard added in v1.2.69

func NewDesktopSessionGuard(sessionID string, target DesktopTarget, startUnix int64) (DesktopSessionGuard, error)

func (*DesktopSessionGuard) ApplyMediaAck added in v1.2.69

func (g *DesktopSessionGuard) ApplyMediaAck(
	window *DesktopMediaCreditWindow,
	ack DesktopMediaAck,
	mediaSessionID string,
	localAgentID string,
	currentGatewayID string,
	nowUnix int64,
) error

ApplyMediaAck validates a browser/gateway acknowledgement against the active session guard and applies it to the sender credit window as one operation. This keeps route, lifetime, session/media binding, and replay checks on the same path before sender flow-control state mutates.

func (*DesktopSessionGuard) LastActivityUnix added in v1.2.69

func (g *DesktopSessionGuard) LastActivityUnix() int64

func (*DesktopSessionGuard) SessionID added in v1.2.69

func (g *DesktopSessionGuard) SessionID() string

func (*DesktopSessionGuard) Target added in v1.2.69

func (g *DesktopSessionGuard) Target() DesktopTarget

func (*DesktopSessionGuard) ValidateContentRecording added in v1.2.69

func (g *DesktopSessionGuard) ValidateContentRecording(frame DesktopFrame) error

ValidateContentRecording checks whether retaining the sensitive content from an already accepted frame is allowed by this session's recording policy. Metadata-only audit paths do not need this check; screen pixels and clipboard bytes must pass it before being persisted or exported.

func (*DesktopSessionGuard) ValidateFrame added in v1.2.69

func (g *DesktopSessionGuard) ValidateFrame(
	frame DesktopFrame,
	localAgentID string,
	currentGatewayID string,
	nowUnix int64,
	nowUnixNano int64,
) error

ValidateFrame applies the current session guard before an adapter consumes or emits a desktop frame. Accepted frames update last-activity time after all validation and quota checks succeed.

func (*DesktopSessionGuard) ValidateMediaAck added in v1.2.69

func (g *DesktopSessionGuard) ValidateMediaAck(
	ack DesktopMediaAck,
	mediaSessionID string,
	localAgentID string,
	currentGatewayID string,
	nowUnix int64,
) error

ValidateMediaAck applies the session guard to a browser/gateway SRDP media acknowledgement before the ack mutates sender credit-window state.

func (*DesktopSessionGuard) ValidateMediaFrame added in v1.2.69

func (g *DesktopSessionGuard) ValidateMediaFrame(
	frame DesktopMediaFrame,
	localAgentID string,
	currentGatewayID string,
	nowUnix int64,
) error

ValidateMediaFrame applies the session guard to a dedicated SRDP media frame before the gateway or adapter accepts screen/cursor/media payloads.

type DesktopTLSPolicy added in v1.2.69

type DesktopTLSPolicy struct {
	Mode        string `json:"mode"`
	CABundleID  string `json:"ca_bundle_id,omitempty"`
	CABundlePEM string `json:"ca_bundle_pem,omitempty"`
	NLAMode     string `json:"nla_mode,omitempty"`
	ServerName  string `json:"server_name,omitempty"`
}

type DesktopTarget added in v1.2.69

type DesktopTarget struct {
	TargetID         string                   `json:"target_id"`
	DisplayName      string                   `json:"display_name,omitempty"`
	DeviceUID        string                   `json:"device_uid,omitempty"`
	Protocol         string                   `json:"protocol"`
	Route            DesktopRoute             `json:"route"`
	Upstream         DesktopUpstream          `json:"upstream"`
	TLS              DesktopTLSPolicy         `json:"tls"`
	Credential       DesktopCredentialPolicy  `json:"credential"`
	Screen           DesktopScreenPolicy      `json:"screen"`
	Redirection      DesktopRedirectionPolicy `json:"redirection"`
	ApprovalRequired bool                     `json:"approval_required,omitempty"`
	Recording        DesktopRecordingPolicy   `json:"recording"`
	Metadata         map[string]string        `json:"metadata,omitempty"`
}

DesktopTarget describes one registered desktop target and its immutable per-session policy snapshot.

func NormalizeDesktopTarget added in v1.2.69

func NormalizeDesktopTarget(target DesktopTarget) (DesktopTarget, error)

NormalizeDesktopTarget applies secure defaults and validates the registered desktop target policy snapshot.

type DesktopUpstream added in v1.2.69

type DesktopUpstream struct {
	Host string `json:"host"`
	Port uint32 `json:"port"`
}

type EnhancedEvent

type EnhancedEvent struct {
	EventType             string            `json:"event_type"`
	SessionID             string            `json:"session_id"`
	Protocol              string            `json:"protocol,omitempty"`
	ActorID               string            `json:"actor_id,omitempty"`
	AgentID               string            `json:"agent_id,omitempty"`
	GatewayID             string            `json:"gateway_id,omitempty"`
	Target                map[string]string `json:"target,omitempty"`
	CredentialCustodyMode string            `json:"credential_custody_mode,omitempty"`
	TimestampUnixNano     int64             `json:"timestamp_unix_nano"`
	PID                   int               `json:"pid,omitempty"`
	PPID                  int               `json:"ppid,omitempty"`
	UID                   int               `json:"uid,omitempty"`
	GID                   int               `json:"gid,omitempty"`
	CommandPath           string            `json:"command_path,omitempty"`
	Argv                  []string          `json:"argv,omitempty"`
	CWD                   string            `json:"cwd,omitempty"`
	ExitStatus            *int              `json:"exit_status,omitempty"`
	FilePath              string            `json:"file_path,omitempty"`
	FileOperation         string            `json:"file_operation,omitempty"`
	NetworkProtocol       string            `json:"network_protocol,omitempty"`
	SourceAddress         string            `json:"source_address,omitempty"`
	SourcePort            int               `json:"source_port,omitempty"`
	DestinationAddress    string            `json:"destination_address,omitempty"`
	DestinationPort       int               `json:"destination_port,omitempty"`
	Result                string            `json:"result,omitempty"`
	DroppedEvents         uint64            `json:"dropped_events,omitempty"`
	Metadata              map[string]string `json:"metadata,omitempty"`
}

EnhancedEvent is the clean-room normalized event shape emitted by future Linux collectors. It intentionally excludes terminal bytes and file contents.

type EnhancedEventSource

type EnhancedEventSource interface {
	Start(context.Context, EnhancedRecordingSession) (<-chan EnhancedEvent, func(context.Context) error, error)
}

EnhancedEventSource starts a concrete host-event collector. Linux BPF probes implement this boundary; tests can inject synthetic event sources without carrying kernel or privilege requirements.

type EnhancedRecorder

type EnhancedRecorder interface {
	Start(context.Context, EnhancedRecordingSession) (EnhancedRecording, error)
}

EnhancedRecorder starts a collector for a single remote-access session.

func NewPlatformEnhancedRecorder

func NewPlatformEnhancedRecorder() EnhancedRecorder

NewPlatformEnhancedRecorder returns the Linux host-event fallback collector. It reads public procfs surfaces and refuses required BPF policies unless the policy explicitly allows fallback.

type EnhancedRecording

type EnhancedRecording interface {
	Events() <-chan EnhancedEvent
	Stop(context.Context) error
}

EnhancedRecording is a running collector instance scoped to one session.

type EnhancedRecordingPolicy

type EnhancedRecordingPolicy struct {
	Enabled                 bool   `json:"enabled,omitempty"`
	Required                bool   `json:"required,omitempty"`
	Mode                    string `json:"mode,omitempty"`
	AllowFallback           bool   `json:"allow_fallback,omitempty"`
	IncludeCommandArguments bool   `json:"include_command_arguments,omitempty"`
	IncludeFilePaths        bool   `json:"include_file_paths,omitempty"`
	IncludeNetworkAddresses bool   `json:"include_network_addresses,omitempty"`
}

EnhancedRecordingPolicy is the agent-visible subset of the platform policy. It controls whether host-event tracing is required before target access opens and which sensitive fields are allowed in emitted events.

type EnhancedRecordingSession

type EnhancedRecordingSession struct {
	SessionID             string
	Protocol              string
	AgentID               string
	GatewayID             string
	Target                map[string]string
	TargetExecutionMode   string
	CredentialCustodyMode string
	Policy                EnhancedRecordingPolicy
}

EnhancedRecordingSession identifies the remote-access session being traced.

type ErrorReason

type ErrorReason func(error) string

ErrorReason maps internal errors to user-facing frame reasons.

type FileTransferAckPayload added in v1.2.60

type FileTransferAckPayload struct {
	TransferID string `json:"transfer_id"`
	Sequence   uint64 `json:"sequence"`
	Offset     int64  `json:"offset"`
}

FileTransferAckPayload acknowledges receipt or application of a data chunk.

func (FileTransferAckPayload) Validate added in v1.2.60

func (p FileTransferAckPayload) Validate() error

Validate verifies the chunk acknowledgement schema.

type FileTransferDataPayload added in v1.2.60

type FileTransferDataPayload struct {
	TransferID string `json:"transfer_id"`
	Sequence   uint64 `json:"sequence"`
	Offset     int64  `json:"offset"`
	Data       []byte `json:"data,omitempty"`
	EOF        bool   `json:"eof,omitempty"`
}

FileTransferDataPayload carries a bounded chunk of file bytes. When this struct is JSON-encoded, Data is base64-encoded by encoding/json.

func (FileTransferDataPayload) Validate added in v1.2.60

func (p FileTransferDataPayload) Validate() error

Validate verifies the chunk data schema.

type FileTransferDirection added in v1.2.60

type FileTransferDirection string

FileTransferDirection groups operations into read, write, and management buckets for RBAC, approval, quota, and recording policy.

func DirectionForOperation added in v1.2.60

func DirectionForOperation(operation FileTransferOperation) (FileTransferDirection, error)

DirectionForOperation returns the default RBAC/policy direction for an operation.

func (FileTransferDirection) Valid added in v1.2.60

func (d FileTransferDirection) Valid() bool

Valid returns true when the direction maps to a file-transfer RBAC group.

type FileTransferEntry added in v1.2.60

type FileTransferEntry struct {
	Name    string    `json:"name"`
	Path    string    `json:"path,omitempty"`
	Size    int64     `json:"size"`
	Mode    string    `json:"mode"`
	IsDir   bool      `json:"is_dir"`
	ModTime time.Time `json:"mod_time"`
}

FileTransferEntry is safe directory or stat metadata returned by SFTP reads.

type FileTransferErrorPayload added in v1.2.60

type FileTransferErrorPayload struct {
	TransferID   string             `json:"transfer_id"`
	ApprovalID   string             `json:"approval_id,omitempty"`
	Status       FileTransferStatus `json:"status"`
	Code         string             `json:"code"`
	Message      string             `json:"message,omitempty"`
	RedactedPath string             `json:"redacted_path,omitempty"`
	PathHash     string             `json:"path_hash,omitempty"`
}

FileTransferErrorPayload reports a denied, failed, canceled, or quota-exhausted transfer.

type FileTransferOperation added in v1.2.60

type FileTransferOperation string

FileTransferOperation identifies a policy-gated remote filesystem action.

func (FileTransferOperation) Valid added in v1.2.60

func (o FileTransferOperation) Valid() bool

Valid returns true when the operation is part of the first SFTP slice.

type FileTransferOutcomePayload added in v1.2.60

type FileTransferOutcomePayload struct {
	TransferID       string             `json:"transfer_id"`
	ApprovalID       string             `json:"approval_id,omitempty"`
	Status           FileTransferStatus `json:"status"`
	BytesTransferred int64              `json:"bytes_transferred,omitempty"`
	FilesTransferred int64              `json:"files_transferred,omitempty"`
	SHA256           string             `json:"sha256,omitempty"`
	RedactedPath     string             `json:"redacted_path,omitempty"`
	PathHash         string             `json:"path_hash,omitempty"`
	FailureReason    string             `json:"failure_reason,omitempty"`
}

FileTransferOutcomePayload reports the durable outcome metadata for audit and replay.

type FileTransferPolicy added in v1.2.60

type FileTransferPolicy struct {
	AllowedOperations  []FileTransferOperation `json:"allowed_operations,omitempty"`
	AllowedPathRules   []string                `json:"allowed_path_rules,omitempty"`
	DeniedPathRules    []string                `json:"denied_path_rules,omitempty"`
	RedactedPathRules  []string                `json:"redacted_path_rules,omitempty"`
	SymlinkMode        FileTransferSymlinkMode `json:"symlink_mode,omitempty"`
	MaxBytes           int64                   `json:"max_bytes,omitempty"`
	MaxFiles           int64                   `json:"max_files,omitempty"`
	RequiresApproval   bool                    `json:"requires_approval,omitempty"`
	ContentAuditRetain bool                    `json:"content_audit_retain,omitempty"`
}

FileTransferPolicy is the policy snapshot the selected agent must enforce before and during target file operations.

type FileTransferPolicyDecision added in v1.2.60

type FileTransferPolicyDecision struct {
	Allowed            bool               `json:"allowed"`
	Status             FileTransferStatus `json:"status"`
	Reason             string             `json:"reason,omitempty"`
	NormalizedPath     string             `json:"normalized_path,omitempty"`
	RedactedPath       string             `json:"redacted_path,omitempty"`
	PathHash           string             `json:"path_hash,omitempty"`
	ContentAuditRetain bool               `json:"content_audit_retain,omitempty"`
}

FileTransferPolicyDecision is safe to persist in audit and replay streams.

func EvaluateFileTransferPolicy added in v1.2.60

func EvaluateFileTransferPolicy(input FileTransferPolicyInput, policy FileTransferPolicy) (FileTransferPolicyDecision, error)

EvaluateFileTransferPolicy applies the agent-enforced policy gates for a transfer. It does not open files and does not inspect file contents.

type FileTransferPolicyInput added in v1.2.60

type FileTransferPolicyInput struct {
	Request                 FileTransferRequestPayload
	ResolvedPath            string
	ResolvedDestinationPath string
	Bytes                   int64
	Files                   int64
	HasSymlink              bool
	HasDestinationSymlink   bool
	RealPathOK              bool
	DestinationRealPathOK   bool
	Approved                bool
}

FileTransferPolicyInput carries the trusted transfer request plus target filesystem facts observed by the selected agent.

type FileTransferProgressPayload added in v1.2.60

type FileTransferProgressPayload struct {
	TransferID       string             `json:"transfer_id"`
	Status           FileTransferStatus `json:"status"`
	BytesTransferred int64              `json:"bytes_transferred,omitempty"`
	FilesTransferred int64              `json:"files_transferred,omitempty"`
	TotalBytes       int64              `json:"total_bytes,omitempty"`
	RedactedPath     string             `json:"redacted_path,omitempty"`
	PathHash         string             `json:"path_hash,omitempty"`
}

FileTransferProgressPayload reports transfer lifecycle progress. Payloads must contain counters and redacted/hashable path metadata only, never file contents.

type FileTransferRequestPayload added in v1.2.60

type FileTransferRequestPayload struct {
	Protocol        string                `json:"protocol,omitempty"`
	TransferID      string                `json:"transfer_id"`
	SessionID       string                `json:"session_id"`
	Operation       FileTransferOperation `json:"operation"`
	Direction       FileTransferDirection `json:"direction,omitempty"`
	Path            string                `json:"path"`
	DestinationPath string                `json:"destination_path,omitempty"`
	DisplayName     string                `json:"display_name,omitempty"`
	Policy          FileTransferPolicy    `json:"policy,omitempty"`
	Approved        bool                  `json:"approved,omitempty"`
	ApprovalID      string                `json:"approval_id,omitempty"`
}

FileTransferRequestPayload is the JSON payload carried by FrameTypeFileTransferRequest. Route, agent, gateway, target host, credential, custody, recording, and approval override fields are not accepted from browser intent; the trusted control plane adds the policy snapshot and approval binding that the selected agent must enforce before it opens target file handles.

func (FileTransferRequestPayload) Validate added in v1.2.60

func (p FileTransferRequestPayload) Validate() error

Validate verifies the bounded client intent schema before route/session context is applied.

type FileTransferResult added in v1.2.60

type FileTransferResult struct {
	Outcome FileTransferOutcomePayload
	Entries []FileTransferEntry
}

FileTransferResult returns transfer metadata without file contents.

type FileTransferStatus added in v1.2.60

type FileTransferStatus string

FileTransferStatus is the stable status vocabulary used by frames, audit, and replay.

type FileTransferSymlinkMode added in v1.2.60

type FileTransferSymlinkMode string

FileTransferSymlinkMode controls how agent-side policy handles target symlinks.

const (
	FileTransferSymlinkDeny             FileTransferSymlinkMode = "deny"
	FileTransferSymlinkFollowInsideRoot FileTransferSymlinkMode = "follow_inside_root"
	FileTransferSymlinkAllow            FileTransferSymlinkMode = "allow"
)

func (FileTransferSymlinkMode) Valid added in v1.2.60

func (m FileTransferSymlinkMode) Valid() bool

Valid returns true for supported symlink modes. Empty defaults to deny.

type Frame

type Frame struct {
	SessionID     string
	Protocol      string
	FrameType     string
	Data          []byte
	Cols          uint32
	Rows          uint32
	Reason        string
	Timestamp     int64
	Seq           uint64
	PayloadSHA256 string
	Signature     string
	Metadata      map[string]string
}

Frame is the agent-local representation of a remote-access control frame. It intentionally mirrors the OpenSpec frame vocabulary before protobuf compatibility wrappers map it to existing ConsoleFrame traffic.

type FrameAuthenticator added in v1.2.69

type FrameAuthenticator struct {
	// contains filtered or unexported fields
}

FrameAuthenticator signs agent-to-broker frames for a single remote-access session. It is safe for concurrent use by PTY, recording, and transfer loops.

func NewFrameAuthenticatorFromOpenPayload added in v1.2.69

func NewFrameAuthenticatorFromOpenPayload(data []byte) (*FrameAuthenticator, error)

NewFrameAuthenticatorFromOpenPayload extracts a per-session frame signing key from broker-generated open-frame JSON.

func (*FrameAuthenticator) Sign added in v1.2.69

func (a *FrameAuthenticator) Sign(frame Frame, agentID string) Frame

Sign binds a frame to the authenticated session route and assigns the next monotonic sequence number.

type KnownHostsStore added in v1.4.95

type KnownHostsStore struct {
	// contains filtered or unexported fields
}

KnownHostsStore serializes trust-on-first-use pins into known_hosts files. A pin reads the file and then appends to it, so two sessions pinning at once would each miss the other's line. Every SSH path in the agent that can pin a host key (remote access sessions, file transfers and the Proxmox console) shares one store. The zero value is ready to use.

func (*KnownHostsStore) HostKeyCallback added in v1.4.95

func (s *KnownHostsStore) HostKeyCallback(policy, knownHostsPath string) (ssh.HostKeyCallback, error)

HostKeyCallback returns the configured host-key verification callback for agent-routed SSH sessions. A nil store refuses trust_on_first_use.

type LinuxProcEnhancedEventSource

type LinuxProcEnhancedEventSource struct {
	// contains filtered or unexported fields
}

LinuxProcEnhancedEventSource is a clean-room Linux fallback collector. It polls procfs for process, fd, and socket state and normalizes observations into enhanced-recording events. It is not a BPF collector; required BPF policies must either use a future BPF source or explicitly allow fallback.

func NewLinuxProcEnhancedEventSource

func NewLinuxProcEnhancedEventSource(opts ...LinuxProcOption) *LinuxProcEnhancedEventSource

NewLinuxProcEnhancedEventSource returns a procfs-backed enhanced event source.

func (*LinuxProcEnhancedEventSource) Start

type LinuxProcOption

type LinuxProcOption func(*LinuxProcEnhancedEventSource)

LinuxProcOption configures LinuxProcEnhancedEventSource.

func WithLinuxProcEventBuffer

func WithLinuxProcEventBuffer(size int) LinuxProcOption

WithLinuxProcEventBuffer configures the event channel buffer.

func WithLinuxProcPollInterval

func WithLinuxProcPollInterval(interval time.Duration) LinuxProcOption

WithLinuxProcPollInterval configures the procfs polling interval.

func WithLinuxProcRoot

func WithLinuxProcRoot(path string) LinuxProcOption

WithLinuxProcRoot points the collector at a procfs root. It is primarily for tests.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager routes generic remote-access frames to active adapter sessions.

func NewManager

func NewManager(opener Opener) *Manager

NewManager creates a remote-access session manager. A nil opener reports ErrAdapterUnavailable for open frames until the caller provides one.

func NewManagerWithConfig

func NewManagerWithConfig(cfg ManagerConfig) *Manager

NewManagerWithConfig creates a remote-access session manager with optional compatibility hooks for callers that are adapting an existing protocol.

func (*Manager) HandleFrame

func (m *Manager) HandleFrame(ctx context.Context, frame Frame, sender Sender)

HandleFrame applies one incoming control frame to the addressed session.

type ManagerConfig

type ManagerConfig struct {
	Opener           Opener
	ErrorReason      ErrorReason
	EnhancedRecorder EnhancedRecorder
}

ManagerConfig configures a remote-access session manager.

type Opener

type Opener func(context.Context, Frame) (PTY, error)

Opener opens a protocol-specific target adapter for an open frame.

type PTY

type PTY interface {
	Read(context.Context) ([]byte, error)
	Write([]byte) error
	Resize(cols, rows uint32) error
	Close() error
}

PTY is the byte-oriented terminal interface exposed by terminal protocols.

func OpenSSHFromFrame

func OpenSSHFromFrame(ctx context.Context, frame Frame, opts SSHOpenOptions) (PTY, error)

OpenSSHFromFrame opens an SSH PTY from a generic remote-access open frame.

func OpenSSHPTY

func OpenSSHPTY(ctx context.Context, cfg SSHConfig, dial SSHDialer) (PTY, error)

OpenSSHPTY opens an SSH shell and exposes it as a remoteaccess PTY.

type RDPAdapterCapabilities added in v1.2.69

type RDPAdapterCapabilities struct {
	Schema                string `json:"schema"`
	Protocol              string `json:"protocol"`
	HelperProtocolVersion int    `json:"helper_protocol_version"`
	IronRDPBackendLinked  bool   `json:"ironrdp_backend_linked"`
	ConnectorReady        bool   `json:"connector_ready"`
	ConnectorReadyReason  string `json:"connector_ready_reason,omitempty"`
}

func ProbeRDPAdapterCapabilities added in v1.2.69

func ProbeRDPAdapterCapabilities(
	ctx context.Context,
	path string,
) (string, RDPAdapterCapabilities, error)

type RemoteAccessStreamStatus added in v1.2.67

type RemoteAccessStreamStatus string

RemoteAccessStreamStatus is the status vocabulary shared by app/TCP progress, error, and outcome frames.

func (RemoteAccessStreamStatus) Valid added in v1.2.67

func (s RemoteAccessStreamStatus) Valid() bool

Valid returns true when the stream status is part of the app/TCP audit vocabulary.

type SFTPAdapter added in v1.2.60

type SFTPAdapter struct {
	Dial           SFTPDialer
	Policy         FileTransferPolicy
	Approved       bool
	MaxChunkBytes  int
	ChmodMode      os.FileMode
	ChmodModeSet   bool
	ChownUID       int
	ChownGID       int
	ChownSet       bool
	KnownHostsPath string
	KnownHosts     *KnownHostsStore
}

SFTPAdapter executes policy-gated SFTP operations.

func (SFTPAdapter) Execute added in v1.2.60

func (a SFTPAdapter) Execute(
	ctx context.Context,
	cfg SSHConfig,
	request FileTransferRequestPayload,
	input io.Reader,
	output io.Writer,
) (FileTransferResult, error)

Execute runs one SFTP operation. File contents are streamed only through the supplied input/output handles and are not retained by the adapter.

type SFTPClient added in v1.2.60

type SFTPClient interface {
	io.Closer
	Chmod(path string, mode os.FileMode) error
	Chown(path string, uid int, gid int) error
	Create(path string) (SFTPFile, error)
	Lstat(path string) (os.FileInfo, error)
	Mkdir(path string) error
	Open(path string) (SFTPFile, error)
	ReadDir(path string) ([]os.FileInfo, error)
	RealPath(path string) (string, error)
	Remove(path string) error
	Rename(oldname string, newname string) error
	Stat(path string) (os.FileInfo, error)
}

SFTPClient is the subset of github.com/pkg/sftp.Client used by the adapter.

type SFTPDialer added in v1.2.60

type SFTPDialer func(context.Context, SSHConfig) (SFTPClient, error)

SFTPDialer opens an SFTP client using session-scoped SSH configuration.

type SFTPFile added in v1.2.60

type SFTPFile interface {
	io.Reader
	io.Writer
	io.Closer
}

SFTPFile is the file handle subset used for upload and download.

type SSHAuth

type SSHAuth struct {
	Username    string `json:"username,omitempty"`
	Password    string `json:"password,omitempty"`
	PrivateKey  string `json:"private_key,omitempty"`
	Passphrase  string `json:"passphrase,omitempty"`
	Certificate string `json:"certificate,omitempty"`
}

SSHAuth contains session-scoped SSH credentials. Callers must not persist private keys, passwords, or passphrases when using user-present custody.

type SSHConfig

type SSHConfig struct {
	Target             SSHTarget
	Auth               SSHAuth
	TerminalType       string
	Cols               uint32
	Rows               uint32
	Timeout            time.Duration
	SSHHostKeyPolicy   string
	SSHHostKeyApproval *SSHHostKeyApproval
	KnownHostsPath     string
	// KnownHosts serializes trust-on-first-use pins into KnownHostsPath. Nil
	// refuses every policy that would pin a key.
	KnownHosts *KnownHostsStore
}

SSHConfig configures an SSH-backed PTY adapter.

func SSHConfigFromOpenFrame

func SSHConfigFromOpenFrame(frame Frame) (SSHConfig, error)

SSHConfigFromOpenFrame decodes and validates an SSH open frame.

type SSHDialer

type SSHDialer func(context.Context, SSHConfig) (SSHSession, error)

SSHDialer opens an SSH session for tests or alternate transports.

type SSHHostKeyApproval added in v1.4.52

type SSHHostKeyApproval struct {
	Target      string `json:"target"`
	Fingerprint string `json:"fingerprint"`
}

type SSHOpenOptions

type SSHOpenOptions struct {
	Dial           SSHDialer
	KnownHostsPath string
	KnownHosts     *KnownHostsStore
}

SSHOpenOptions configures frame-to-PTY SSH opening.

type SSHOpenPayload

type SSHOpenPayload struct {
	Protocol           string              `json:"protocol,omitempty"`
	SessionID          string              `json:"session_id,omitempty"`
	AgentID            string              `json:"agent_id,omitempty"`
	GatewayID          string              `json:"gateway_id,omitempty"`
	Target             SSHTarget           `json:"target"`
	SSH                SSHAuth             `json:"ssh,omitempty"`
	CredentialMode     string              `json:"credential_mode,omitempty"`
	TerminalType       string              `json:"terminal_type,omitempty"`
	TimeoutMS          int                 `json:"timeout_ms,omitempty"`
	SSHHostKeyPolicy   string              `json:"ssh_host_key_policy,omitempty"`
	SSHHostKeyApproval *SSHHostKeyApproval `json:"ssh_host_key_approval,omitempty"`
}

SSHOpenPayload is the JSON payload carried by an SSH open frame.

type SSHSession

type SSHSession interface {
	StdinPipe() (io.WriteCloser, error)
	StdoutPipe() (io.Reader, error)
	StderrPipe() (io.Reader, error)
	RequestPty(term string, h, w int) error
	WindowChange(h, w int) error
	Shell() error
	Wait() error
	Close() error
}

SSHSession is the subset of x/crypto/ssh.Session used by the PTY adapter.

func DialSSH

func DialSSH(ctx context.Context, cfg SSHConfig) (SSHSession, error)

DialSSH opens a real SSH session using x/crypto/ssh.

type SSHTarget

type SSHTarget struct {
	Host string `json:"host,omitempty"`
	Port int    `json:"port,omitempty"`
}

SSHTarget identifies the target host opened by the selected agent.

type Sender

type Sender interface {
	SendFrame(Frame) error
}

Sender emits frames back to the gateway/control-plane route.

type SourceEnhancedRecorder

type SourceEnhancedRecorder struct {
	// contains filtered or unexported fields
}

SourceEnhancedRecorder adapts a collector source to the manager's EnhancedRecorder interface.

func NewSourceEnhancedRecorder

func NewSourceEnhancedRecorder(source EnhancedEventSource) *SourceEnhancedRecorder

NewSourceEnhancedRecorder returns an EnhancedRecorder backed by source.

func (*SourceEnhancedRecorder) Start

type TCPAdapter added in v1.2.67

type TCPAdapter struct {
	// contains filtered or unexported fields
}

func NewTCPAdapter added in v1.2.67

func NewTCPAdapter(ctx context.Context, open TCPOpenPayload, opts TCPAdapterOptions) (*TCPAdapter, error)

func (*TCPAdapter) Close added in v1.2.67

func (a *TCPAdapter) Close() error

func (*TCPAdapter) Read added in v1.2.67

func (a *TCPAdapter) Read(ctx context.Context, maxChunkBytes int) (TCPDataPayload, TCPProgressPayload, error)

func (*TCPAdapter) Write added in v1.2.67

type TCPAdapterOptions added in v1.2.67

type TCPAdapterOptions struct {
	DialContext TCPDialer
}

type TCPClosePayload added in v1.2.67

type TCPClosePayload struct {
	SessionID    string `json:"session_id"`
	ConnectionID string `json:"connection_id"`
	Reason       string `json:"reason,omitempty"`
}

TCPClosePayload reports an orderly TCP connection close.

func (TCPClosePayload) Validate added in v1.2.67

func (p TCPClosePayload) Validate() error

type TCPDataDirection added in v1.2.67

type TCPDataDirection string

TCPDataDirection marks whether bounded bytes flow toward the TCP upstream or back toward the client renderer.

func (TCPDataDirection) Valid added in v1.2.67

func (d TCPDataDirection) Valid() bool

Valid returns true when the TCP data direction is part of the frame contract.

type TCPDataPayload added in v1.2.67

type TCPDataPayload struct {
	SessionID    string           `json:"session_id"`
	ConnectionID string           `json:"connection_id"`
	Direction    TCPDataDirection `json:"direction"`
	Sequence     uint64           `json:"sequence"`
	Data         []byte           `json:"data,omitempty"`
	EOF          bool             `json:"eof,omitempty"`
}

TCPDataPayload carries one bounded byte chunk for an explicitly registered TCP target.

func (TCPDataPayload) Validate added in v1.2.67

func (p TCPDataPayload) Validate() error

type TCPDialer added in v1.2.67

type TCPDialer func(context.Context, string, string) (net.Conn, error)

type TCPErrorPayload added in v1.2.67

type TCPErrorPayload struct {
	SessionID    string                   `json:"session_id"`
	ConnectionID string                   `json:"connection_id,omitempty"`
	Status       RemoteAccessStreamStatus `json:"status"`
	Code         string                   `json:"code"`
	Message      string                   `json:"message,omitempty"`
}

TCPErrorPayload reports a denied, failed, or quota-exhausted TCP stream.

func (TCPErrorPayload) Validate added in v1.2.67

func (p TCPErrorPayload) Validate() error

type TCPOpenPayload added in v1.2.67

type TCPOpenPayload struct {
	TargetID                string            `json:"target_id"`
	SessionID               string            `json:"session_id"`
	ConnectionID            string            `json:"connection_id"`
	UpstreamHost            string            `json:"upstream_host"`
	UpstreamPort            int               `json:"upstream_port"`
	ProtocolName            string            `json:"protocol_name,omitempty"`
	IdleTimeoutSeconds      int               `json:"idle_timeout_seconds,omitempty"`
	AbsoluteTimeoutSeconds  int               `json:"absolute_timeout_seconds,omitempty"`
	QuotaPolicy             map[string]any    `json:"quota_policy,omitempty"`
	ApprovalID              string            `json:"approval_id,omitempty"`
	RecordingPolicy         map[string]any    `json:"recording_policy,omitempty"`
	EnhancedRecordingPolicy map[string]any    `json:"enhanced_recording_policy,omitempty"`
	Metadata                map[string]string `json:"metadata,omitempty"`
}

TCPOpenPayload is carried by FrameTypeTCPOpen after target policy resolution.

func (TCPOpenPayload) Validate added in v1.2.67

func (p TCPOpenPayload) Validate() error

type TCPOutcomePayload added in v1.2.67

type TCPOutcomePayload struct {
	SessionID     string                   `json:"session_id"`
	TargetID      string                   `json:"target_id"`
	ConnectionID  string                   `json:"connection_id"`
	Status        RemoteAccessStreamStatus `json:"status"`
	BytesIn       int64                    `json:"bytes_in,omitempty"`
	BytesOut      int64                    `json:"bytes_out,omitempty"`
	FailureReason string                   `json:"failure_reason,omitempty"`
}

TCPOutcomePayload reports durable TCP metadata for audit and replay.

func (TCPOutcomePayload) Validate added in v1.2.67

func (p TCPOutcomePayload) Validate() error

type TCPProgressPayload added in v1.2.67

type TCPProgressPayload struct {
	SessionID    string                   `json:"session_id"`
	ConnectionID string                   `json:"connection_id"`
	Status       RemoteAccessStreamStatus `json:"status"`
	BytesIn      int64                    `json:"bytes_in,omitempty"`
	BytesOut     int64                    `json:"bytes_out,omitempty"`
}

TCPProgressPayload reports TCP connection lifecycle and byte-count metadata.

func (TCPProgressPayload) Validate added in v1.2.67

func (p TCPProgressPayload) Validate() error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址