deviceforward

type Bundle struct {
	Server       string          `json:"server"`
	Token        string          `json:"token"`
	Pin          string          `json:"pin,omitempty"`
	EnrollmentID string          `json:"enrollment_id"`
	Name         string          `json:"name"`
	Device       ForwardedDevice `json:"device"`
	ExpiresAt    time.Time       `json:"expires_at"`
}

type ByePayload struct {
	Reason    string `json:"reason,omitempty"`
	Reconnect bool   `json:"reconnect"`
}

type Credential struct {
	Server      string          `json:"server"`
	ForwarderID string          `json:"forwarder_id"`
	Credential  string          `json:"credential"`
	Name        string          `json:"name,omitempty"`
	Device      ForwardedDevice `json:"device"`
	Pin         string          `json:"pin,omitempty"`
}

type DeviceKind string

type DeviceStream struct {
	io.ReadWriteCloser
	ForwarderID string
	Device      ForwardedDevice
	Exported    ExportedDevice
}

type DialFunc func(ctx context.Context, server, token string) (frameConn, error)

type EnrollmentRecord struct {
	ID         string          `json:"id"`
	Name       string          `json:"name"`
	SecretHash string          `json:"secret_hash"`
	Device     ForwardedDevice `json:"device"`
	CreatedAt  time.Time       `json:"created_at"`
	ExpiresAt  time.Time       `json:"expires_at"`
	CreatedBy  string          `json:"created_by,omitempty"`
	// Owner scopes the forwarder to one identity on a multi-user hub, so a
	// forwarder is listed and revocable by its owner. Empty on a single-user
	// hub.
	Owner           string    `json:"owner,omitempty"`
	RedeemedAt      time.Time `json:"redeemed_at,omitempty"`
	RedeemedAgentID string    `json:"redeemed_agent_id,omitempty"`
	RevokedAt       time.Time `json:"revoked_at,omitempty"`
}

type ErrorPayload struct {
	Message string `json:"message"`
}

type ExportedDevice struct {
	Kind      DeviceKind `json:"kind"`
	BusID     string     `json:"bus_id,omitempty"`
	VendorID  string     `json:"vendor_id,omitempty"`
	ProductID string     `json:"product_id,omitempty"`
	// Speed is the kernel's usb_device_speed enum value.
	Speed     uint32 `json:"speed,omitempty"`
	Interface string `json:"interface,omitempty"`
}

type ForwardedDevice struct {
	// Kind selects which of the fields below is meaningful.
	Kind DeviceKind `json:"kind"`
	// USB identifies the forwarded USB device by vendor, product and
	// optionally serial — the identity that survives re-enumeration. Set when
	// Kind is KindUSB.
	USB *executor.USBMatch `json:"usb,omitempty"`
	// Interface is the kernel name of the forwarded network interface on the
	// on-prem host ("eth1", "can0"). Set when Kind is KindL2.
	Interface string `json:"interface,omitempty"`
	// Label is an operator-facing description shown in the dashboard and in
	// audit rows. Optional; a default is derived from the identity when empty.
	Label string `json:"label,omitempty"`
}

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

type ForwarderConfig struct {
	// Server is the full wss://host/api/forwarders/connect URL.
	Server string
	// Token is a bare enrollment token, used only until a credential is saved.
	Token string
	// Bundle, if set, supplies Server/Token/Pin together (explicit fields win).
	Bundle string
	// CredentialPath is where the long-lived credential is saved and loaded.
	CredentialPath string
	// Pin is the hub's SPKI fingerprint; CAFile an extra root; Insecure allows
	// plaintext to a non-loopback host (refused by default).
	Pin      string
	CAFile   string
	Insecure bool
	// Source is the on-prem device endpoint. Required.
	Source LocalSource
	// AgentVersion is the build string reported in the hello.
	AgentVersion string
	// Logf receives operational messages. Nil discards them.
	Logf func(format string, args ...any)
	// Dial overrides the transport, for tests.
	Dial DialFunc
}

type ForwarderRecord struct {
	ForwarderID  string          `json:"forwarder_id"`
	Name         string          `json:"name"`
	SecretHash   string          `json:"secret_hash"`
	Device       ForwardedDevice `json:"device"`
	Owner        string          `json:"owner,omitempty"`
	CreatedAt    time.Time       `json:"created_at"`
	LastSeen     time.Time       `json:"last_seen,omitempty"`
	RevokedAt    time.Time       `json:"revoked_at,omitempty"`
	EnrollmentID string          `json:"enrollment_id,omitempty"`
}

type Frame struct {
	Type    FrameType
	Channel uint32
	Payload []byte
}

type FrameType byte

type HelloPayload struct {
	Version int             `json:"version"`
	Device  ForwardedDevice `json:"device"`
	// AgentVersion is the forwarder build string, for the fleet view.
	AgentVersion string `json:"agent_version,omitempty"`
	// Available reports whether the forwarder can currently reach its device
	// (the USB device is plugged in, the interface exists). A forwarder that
	// connects with its device missing is still useful to see in the UI, so
	// this is advisory, not a refusal.
	Available bool `json:"available"`
	// Detail explains a false Available, for the operator.
	Detail string `json:"detail,omitempty"`
	// Resolved, for a USB device, is what the forwarder found the configured
	// identity resolving to on its host right now — the concrete device, with
	// its current bus/port, so the dashboard can show the real hardware.
	Resolved *executor.USBDevice `json:"resolved,omitempty"`
}

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

type HubOptions struct {
	// Store is the enrollment/credential persistence. Required.
	Store Store
	// OnConnect is called after every successful handshake, with the record
	// and what the forwarder advertised, so the caller can refresh a row.
	OnConnect func(rec ForwarderRecord, hello HelloPayload)
	// OnEnroll is called once, when a token is first redeemed.
	OnEnroll func(rec ForwarderRecord)
	// OnStatusChange mirrors connectivity into durable storage.
	OnStatusChange func(forwarderID, status string, at time.Time)
	// CheckOrigin decides whether a browser Origin may open the socket. Nil
	// accepts same-origin and no-Origin (an agent sets no Origin). The caller
	// passes the hub's own origin policy so the two endpoints judge alike.
	CheckOrigin func(*http.Request) (bool, string)
	// RevocationRecheck is how often a live session re-reads its forwarder's
	// record and ends itself if the credential was revoked meanwhile (Task
	// 20430). It is the backstop under the immediate cut a revocation makes on
	// the member holding the session: a revocation recorded by a process that
	// could not reach this one — the CLI, another hub member — still ends the
	// session within this interval. Zero means DefaultRevocationRecheck.
	RevocationRecheck time.Duration
	// Logf receives operational messages. Now overrides the clock.
	Logf func(format string, args ...any)
	Now  func() time.Time
}

type ImportOptions struct {
	// VHCI is the controller to attach to. Zero means the host's first.
	VHCI VHCI
	// SysfsRoot and DevRoot locate /sys and /dev, for resolving the device
	// once it has enumerated. Empty means the host's.
	SysfsRoot string
	DevRoot   string
	// Ledger, when set, records the attachment so a successor process can
	// sweep it if this one dies holding it.
	Ledger *Ledger
	// EnumerateTimeout bounds the wait for the kernel to enumerate the device
	// after the attach. Zero means 15 seconds.
	EnumerateTimeout time.Duration
	// Logf receives operational messages.
	Logf func(string, ...any)
}

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

type L2SourceOptions struct {
	Logf func(string, ...any)
}

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

type LedgerEntry struct {
	ID       string     `json:"id"`
	Kind     LedgerKind `json:"kind"`
	VHCIRoot string     `json:"vhci_root,omitempty"`
	VHCIPort int        `json:"vhci_port,omitempty"`
	DevID    uint32     `json:"dev_id,omitempty"`
	TAP      string     `json:"tap,omitempty"`
	At       time.Time  `json:"at"`
}

type LedgerKind string

type LocalSource interface {
	// Device is the descriptor this source serves, for the hello.
	Device() ForwardedDevice
	// Probe reports whether the device is reachable right now. resolved, for a
	// USB source, is the concrete device the configured identity matched, so
	// the dashboard can show the real hardware. A false ok is advisory: the
	// forwarder still connects so the operator can see it, and refuses Opens
	// until the device is present.
	Probe(ctx context.Context) (ok bool, detail string, resolved *executor.USBDevice)
	// Open opens a fresh byte stream to the device — a connection to the local
	// usbip server for a USB device, a raw interface handle for L2. The caller
	// closes it when the stream ends.
	Open(ctx context.Context) (io.ReadWriteCloser, error)
	// Close releases anything held across the forwarder's whole life, such as
	// a spawned usbip daemon. Called once at shutdown.
	Close() error
}

type MintOptions struct {
	Name   string
	Device ForwardedDevice
	TTL    time.Duration
	Owner  string
	// CreatedBy identifies the minting operator (OIDC subject, or "" local).
	CreatedBy string
	// Server and Pin go into the bundle the operator carries to the device;
	// they are not persisted.
	Server string
	Pin    string
	Now    func() time.Time
}

type OpenAckPayload struct {
	OK    bool   `json:"ok"`
	Error string `json:"error,omitempty"`
	// Device describes what the forwarder opened (Task 20430): for USB the
	// on-prem bus id a consumer's OP_REQ_IMPORT must name. Additive, so an
	// older forwarder that omits it still interoperates; the hub then falls
	// back to the bus id the forwarder's hello resolved.
	Device *ExportedDevice `json:"device,omitempty"`
}

type OpenPayload struct {
	// Purpose is a short free-form note for the forwarder's log and the audit
	// trail: "attach", "devlist". Advisory only.
	Purpose string `json:"purpose,omitempty"`
}

type ProbeResult struct {
	BusID      string `json:"bus_id"`
	VendorID   string `json:"vendor_id"`
	ProductID  string `json:"product_id"`
	Speed      uint32 `json:"speed"`
	Interfaces int    `json:"interfaces"`
}

type Store interface {
	PutEnrollment(rec EnrollmentRecord) error
	GetEnrollment(id string) (EnrollmentRecord, error)
	RedeemEnrollment(id, forwarderID string, at time.Time) error
	RevokeEnrollment(id string, at time.Time) error
	ListEnrollments() ([]EnrollmentRecord, error)

	PutForwarder(rec ForwarderRecord) error
	GetForwarder(forwarderID string) (ForwarderRecord, error)
	RevokeForwarder(forwarderID string, at time.Time) error
	TouchForwarder(forwarderID string, at time.Time) error
	ListForwarders() ([]ForwarderRecord, error)
}

type SweepReport struct {
	// Detached are the vhci ports detached, as "port N".
	Detached []string
	// Removed are the TAP interfaces removed.
	Removed []string
	// Errors are the entries that could not be undone.
	Errors []string
}

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

type USBImport struct {

	// Port is the vhci port the device is attached to, and DevID the remote
	// device id the kernel recorded for it.
	Port  int
	DevID uint32
	// Remote is what the forwarder exported.
	Remote usbipDevice
	// Device is the device as it enumerated on this host.
	Device executor.USBDevice
	// contains filtered or unexported fields
}

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

type USBSourceOptions struct {
	// SysfsRoot defaults to /sys.
	SysfsRoot string
	// UsbipBinary is the usbip(8) tool used to bind/unbind the device to the
	// usbip-host driver. Defaults to "usbip" resolved on PATH.
	UsbipBinary string
	// Logf receives operational messages.
	Logf func(string, ...any)
}

type VHCI struct {
	// Root is the platform-device directory holding attach, detach and
	// status. Empty means DefaultVHCIRoot.
	Root string
}

type WelcomePayload struct {
	Version int `json:"version"`
	// ForwarderID is the hub's durable ID for this forwarder, echoed so the
	// device can log which identity it is serving as.
	ForwarderID string `json:"forwarder_id"`
	// Credential is the long-lived forwarder credential, non-empty only on the
	// connection that redeemed an enrollment token. The forwarder persists it
	// and reconnects with it; it is shown once and never again.
	Credential string `json:"credential,omitempty"`
}