host

type AgentRefusedError struct {
	Key string
	Err error
}

type AgentUnavailableError struct {
	Socket string
	Err    error
}

type AuthorizedKey struct {
	PublicKeys []ssh.PublicKey
	Comment    string
}

type CredentialMode int

type Fetcher struct {
	Logger *slog.Logger
	// Transport, when set, is the base round tripper for every request. Tests
	// use it to trust httptest certificates; production leaves it nil.
	Transport http.RoundTripper
	// contains filtered or unexported fields
}

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

type GuestIdentityOptions struct {
	// IdentitiesOnly says -i was given: Files is the whole set, each entry
	// must resolve, and no other agent key is offered. An empty Files with
	// IdentitiesOnly is an error, as `upterm host -i` makes it ("private-key
	// was supplied but names no files"); it never falls back to the defaults.
	IdentitiesOnly bool
	Files          []string      // with IdentitiesOnly: -i's entries; otherwise the default files that exist
	AgentSocket    string        // SSH_AUTH_SOCK
	AgentTimeout   time.Duration // bound on listing the agent's keys; 0 = 5 s
	// Passphrase asks for an encrypted key file's passphrase, and returns
	// promptly once ctx ends. It is asked only for a file whose key the agent
	// doesn't hold. Nil leaves such a file unloaded.
	Passphrase func(ctx context.Context, file string) ([]byte, error)
	// OnSkip is told about each key file that didn't load, when another key
	// did: "skipping <file>: <error>". OnAgentSkip is told why the agent
	// failed or ran out of time listing its keys, when a key file loaded
	// instead: "skipping the SSH agent: <error>". A socket nobody listens on
	// is no agent, not one that failed, and isn't told. Both are called
	// before NewGuestIdentity returns; nil is silent.
	OnSkip      func(file string, err error)
	OnAgentSkip func(err error)
}

type Host struct {
	Host string
	// KeepAliveDuration paces the guest sshd's keepalive to each guest. The
	// tunnel's own liveness is Reconnect's.
	KeepAliveDuration time.Duration
	Command           []string
	ForceCommand      []string
	Signers           []ssh.Signer
	// IdentitiesOnly says Signers is the whole identity set, as --private-key
	// makes it: a redial never offers the session key ahead of it.
	IdentitiesOnly bool
	// Reconnect paces the tunnel's liveness and its redials. A field left zero
	// takes its default.
	Reconnect ReconnectTiming
	// HostKey is the key the embedded sshd presents on both its doors and
	// the key the relay is told to expect from this host. A session's key,
	// not the operator's: Signers authenticate the tunnel and are used for
	// nothing else. Left nil, Run generates one for that run and does not
	// keep it, so a Host run twice presents two keys; a caller that needs
	// the public half before Run — the CLI, to pin its own attach — sets it
	// and it is used as given.
	HostKey                 ssh.Signer
	HostKeyCallback         ssh.HostKeyCallback
	AuthorizedKeys          []*AuthorizedKey
	AdminSocketFile         string
	SessionCreatedCallback  func(context.Context, *api.GetSessionResponse) error
	ClientJoinedCallback    func(*api.Client)
	ClientLeftCallback      func(*api.Client)
	Logger                  *slog.Logger
	ReadOnly                bool
	AllowLocalTCPForwarding bool
	// TunnelCallback is told when the tunnel to the relay is lost, and when
	// it is back. It is called on a goroutine of the host's own, one event at
	// a time and in the order they happened, so a callback that takes a while
	// delays only the events behind it, not the redial. Of the events that
	// happen while it is still busy with one, only the latest is kept: it says
	// where things stand.
	TunnelCallback func(TunnelEvent)
	// HideClientIP keeps a guest's address out of its forced command's
	// SSH_CONNECTION and SSH_CLIENT.
	HideClientIP bool
	// AutoAccept says the session was started without anyone confirming it
	// (--accept). With no AuthorizedKeys as well, it is open: anyone with
	// the session ID can join, and nobody was asked. GetSessionResponse.open
	// reports that; it changes nothing about who may join.
	AutoAccept bool
	// FileTransferApprovalRequired says each guest file transfer waits for
	// the host's desktop dialog (no --accept). The daemon sets it, with the
	// SFTPPermissionChecker that shows the dialog. It is reported to readers
	// of the session and changes nothing about what is allowed.
	FileTransferApprovalRequired bool
	// ProxyURL, when non-nil, routes the connection to the upterm server
	// through an HTTP proxy.
	ProxyURL   *url.URL
	PtySize    termsize.Size
	PinPtySize bool
	Term       string

	// AttachSocketFile is where the local attach door is bound. Like
	// AdminSocketFile, supplying it means the caller manages the path and
	// no name is claimed; left empty with AdminSocketFile set, no attach
	// door is served, which is how an embedder that will never attach a
	// terminal says so. Claimed with the name otherwise.
	AttachSocketFile string
	// AttachListeningCallback is called once the attach socket is bound,
	// before the command starts, with the path a client should dial. With
	// AwaitInitialClient set, this is the moment to attach.
	//
	// Called on Run's own goroutine, before the run.Group exists, so it must
	// not block: everything after it — the command, the guest door, the
	// readiness record — waits behind it.
	AttachListeningCallback func(attachSocket string)
	// CommandStartedCallback is called once the hosted command is running,
	// which with AwaitInitialClient is also the news that a client got
	// through the door. A caller whose own attach failed asks this whether
	// there is a session to leave alone.
	//
	// Called on the server's own goroutine, in front of everything the
	// command's start releases, so it must not block.
	CommandStartedCallback func()
	// SessionReadyCallback is called once the session's record has been
	// published: the admin socket is bound, the command is running, and the
	// record a reader would consult already carries the session ID and the
	// status handed to this callback. A caller that tells anyone else the
	// session is up says it here, not from CommandStartedCallback — the
	// command starting is one of the two facts readiness is made of, and the
	// record is written after both. A script that runs `upterm session info`
	// the instant it is told "ready" would otherwise be told "starting" by
	// the record.
	//
	// The status is the one the record was written with, which is ready
	// unless the tunnel is down by then: reconnecting while the host redials
	// it, or disconnected on a relay that cannot take the session back. The
	// caller is told what the record says rather than assuming ready, because
	// the two agreeing is the whole point of the callback.
	//
	// Not called when the record could not be published: the run fails
	// instead, so that nobody is told about a record that was never written.
	// With no session directory — an embedder that supplied its own admin
	// socket — there is no record, and the status is the one the session's
	// facts give.
	//
	// Called once, on the readiness actor's own goroutine, after the write;
	// it must not block.
	SessionReadyCallback func(status string)
	// SessionClaimedCallback is called once the session's name is claimed,
	// with the directory that holds it, before the tunnel is dialled: the
	// first thing a caller can know about a session is its name and its
	// paths, and a caller that relays prompts wants them before any prompt.
	// Not called when AdminSocketFile was supplied, since nothing is claimed.
	//
	// Called on Run's own goroutine; it must not block.
	SessionClaimedCallback func(*sessiondir.Dir)
	// VersionWarningCallback is called when the server's version is
	// incompatible with this host's. Nil logs the mismatch and nothing more:
	// the daemon has no terminal to print to.
	VersionWarningCallback func(*version.CompatibilityResult)
	// RelayWarningCallback is called with what the first connection showed
	// about the relay that will matter if the tunnel drops: that it can't
	// take the session back, or that its certificate doesn't name the host a
	// redial would dial. Nil logs it and nothing more, as for
	// VersionWarningCallback.
	//
	// Called at most once, on Run's own goroutine, after
	// VersionWarningCallback and before SessionCreatedCallback, so whoever
	// prints it prints it ahead of the session; it must not block.
	RelayWarningCallback func(RelayWarning)

	// AwaitInitialClient defers starting the command until the first host
	// client's output subscription is installed, and defers serving guests
	// until the command has started. Foreground use sets it: a command that
	// exits at once — `upterm host -- false` — would otherwise race the local
	// terminal's attach, and lose. Headless use leaves it off.
	AwaitInitialClient bool
	// InitialClientTimeout bounds that wait; zero means
	// internal.DefaultInitialClientTimeout.
	InitialClientTimeout time.Duration

	// StopGrace bounds each step of the command's teardown; zero means
	// internal.DefaultStopGrace.
	StopGrace time.Duration

	// JoinTimeout bounds the wait for the first guest, starting at readiness.
	// Zero waits forever. A running session's timeout can be replaced or
	// disabled over the admin socket (`upterm session set`); each replacement
	// counts from when it is made. The session enforces it independently of its
	// launcher; a guest joining disarms it permanently, even after that guest
	// leaves.
	JoinTimeout time.Duration

	// SFTP configuration
	SFTPDisabled          bool                   // Disable SFTP subsystem entirely (--no-sftp)
	SFTPPermissionChecker sftp.PermissionChecker // Optional: prompts user for SFTP permissions (nil = auto-allow)

	// Name is the session's local name. It determines the socket paths, so
	// they are known before the server is ever contacted. It is unrelated to
	// the server-assigned session ID in the connect string.
	//
	// Ignored when AdminSocketFile is set: supplying a socket is how a caller
	// says it is managing the paths itself, so Run claims no name and there is
	// nothing for this to name. SessionDir stays nil in that case, and no
	// record is published.
	Name string

	// ClaimTimeout bounds how long Run waits for the session registry when it
	// claims its name. Zero uses the package's ClaimTimeout; any other value is
	// used as it is, so zero or less than zero in the package's, or less than
	// zero here, gives the claim no time to wait for a held registry lock.
	ClaimTimeout time.Duration

	// SessionDir is claimed by Run and readable for as long as Run is
	// running. Run clears it on the way out: the directory is released by
	// then, a released Dir may not be touched again, and leaving it here
	// would be leaving a handle to a name that now belongs to whoever claimed
	// it next. Nil when AdminSocketFile was supplied, which is how tests
	// drive Host without taking a name.
	SessionDir *sessiondir.Dir
	// contains filtered or unexported fields
}

type KnownHosts struct {
	File string
	// Stdout takes the prompt and the "Permanently added" warning.
	Stdout io.Writer
	// Proxied suppresses the peer address in the prompt, because through a
	// tunnel it belongs to the proxy rather than to the server.
	Proxied bool
}

type ReconnectTiming struct {
	// PingInterval is how long the tunnel may be silent before it is probed,
	// and PingBound how long a probe has to prompt any bytes at all. The
	// defaults are 15 s and 15 s.
	PingInterval, PingBound time.Duration
	// AttemptDeadline is how long one redial may take, from dialling to a
	// registered tunnel. The default is 30 s.
	AttemptDeadline time.Duration
	// FastBase and FastCap shape the fast schedule: the wait doubles from
	// FastBase up to FastCap. The defaults are 1 s and 30 s.
	FastBase, FastCap time.Duration
	// SlowWait is the least wait on the slow schedule, and SlowJitter the most
	// that is added to it. The defaults are 5 min and 30 s.
	SlowWait, SlowJitter time.Duration
	// ResetAfter is how long a tunnel must have been up before losing it starts
	// the schedule over, so a relay that keeps dropping the tunnel is not
	// redialled at the fast schedule's start each time. The default is 60 s.
	ResetAfter time.Duration
}

type RelayWarning struct {
	Kind RelayWarningKind
	// Host is the hostname the certificate isn't valid for, for
	// CertNotValidForServer; empty otherwise.
	Host string
}

type RelayWarningKind int

type SignerOptions struct {
	PrivateKeys []string
	// IdentitiesOnly makes PrivateKeys the whole identity set, as OpenSSH's
	// IdentitiesOnly does: every entry must resolve to a signer, and no
	// other key the agent holds is offered.
	IdentitiesOnly bool
	// Passphrase is asked for an encrypted key's passphrase. Nil prompts on
	// this process's terminal, which a daemon does not have.
	Passphrase func(file string) ([]byte, error)
	// OnSkip is told about a key file that was skipped and why. Nil is
	// silent, as SignersFromFiles always was.
	OnSkip func(file string, err error)
}

type TunnelEvent struct {
	// Up is false when the tunnel was lost and true when it is back.
	Up bool
	// CanReconnect, on a loss, says whether this relay lets the host
	// reconnect. When it doesn't, the loss is final: guests can't join again
	// until the session is restarted.
	CanReconnect bool
	// RouteChanged, on a return, says the relay registered the session at
	// another node or user than before, so the connect string guests use is
	// not the one they had.
	RouteChanged bool
}

type UserRef struct {
	Provider string // "" for the raw-URL form
	User     string
	Host     string // host[:port] as written; "" means "provider default"
	URL      string // raw-URL form only: the complete .keys URL
	Raw      string // the original string, for error messages
	Mode     CredentialMode
}