sshhosts

package
v0.107.40 Latest Latest
Warning

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

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

Documentation

Overview

Package sshhosts stores the SSH hosts SSHManager may connect to, the projects each host is associated with, and K-brain's own known_hosts file.

Hosts live in <dir>/hosts.json, host keys in <dir>/known_hosts (OpenSSH format); dir is created 0700 and both files are written 0600 through a staging file, the way config.json (which holds provider API keys) is. Secrets (password, private key, private key passphrase, proxy password) are stored as written and never leave the package except to open a connection: Public projects them to "...Configured" flags.

Index

Constants

View Source
const (
	AuthPassword            = "password"
	AuthPrivateKey          = "privateKey"
	AuthKeyboardInteractive = "keyboardInteractive"
)

Auth types, as LiveAgent names them.

View Source
const (
	CredentialSaved       = "saved"
	CredentialMissing     = "missing"
	CredentialInteractive = "interactive"
)

Credential states list_hosts and GET /v1/settings/ssh report.

View Source
const (
	MaxHosts           = 256
	MaxHostsPerProject = 64
)

Limits on what a client may store.

Variables

View Source
var ErrConflict = errors.New("ssh settings changed; reload and retry")

ErrConflict is returned when an update names a base revision that is no longer current.

View Source
var ErrNotFound = errors.New("ssh host not found")

ErrNotFound is returned for an unknown host id.

View Source
var ErrSave = errors.New("save ssh hosts")

ErrSave is returned when the hosts file cannot be written.

Functions

func DeleteHost

func DeleteHost(doc *Document, id string) error

DeleteHost removes the host id and its associations.

func NormalizeAssociations

func NormalizeAssociations(in map[string][]string, hosts []Host) map[string][]string

NormalizeAssociations keys associations by ProjectPathKey, drops ids of hosts not in hosts, duplicates and empty lists, and keeps at most MaxHostsPerProject ids per project. When two spellings of one project collide, the one already in canonical form wins (LiveAgent's rule).

func ParseProxyURL

func ParseProxyURL(raw, fallbackType string) (kind, authority string, err error)

ParseProxyURL splits a proxy address ("host", "host:port" or "scheme://host[:port]") into its kind ("socks5" or "http") and authority. Credentials belong in the username and password fields, so an address with user info is refused.

func ProjectPathKey

func ProjectPathKey(value string) string

ProjectPathKey is the key a project's SSH host associations are stored under. It matches LiveAgent's project_path_key, so associations a client saves for a project path are found again from the run's working directory:

  • Windows-like paths (drive letter, UNC, \\?\ prefix): the extended prefix is dropped, backslashes become slashes, trailing slashes above the root are trimmed and the result is lower-cased.
  • Other paths: trailing slashes are trimmed (the root "/" stays).

Types

type Document

type Document struct {
	Hosts []Host `json:"hosts"`
	// ProjectHostAssociations maps a ProjectPathKey to the ids of the hosts
	// SSHManager may use in that project.
	ProjectHostAssociations map[string][]string `json:"projectHostAssociations"`
}

Document is the stored file.

type DocumentInput

type DocumentInput struct {
	BaseRevision            uint64               `json:"baseRevision,omitempty"`
	Hosts                   *[]HostInput         `json:"hosts,omitempty"`
	ProjectHostAssociations *map[string][]string `json:"projectHostAssociations,omitempty"`
	Revision                any                  `json:"revision,omitempty"`
	KnownHostsPath          any                  `json:"knownHostsPath,omitempty"`
}

DocumentInput is the body of PUT /v1/settings/ssh. A field that is absent keeps what is stored: Hosts, when present, is the complete host list (hosts left out are deleted, secrets of the others follow HostInput's rules); ProjectHostAssociations, when present, replaces every association. BaseRevision, when non-zero, must be the current revision. Revision and knownHostsPath from GET are accepted and ignored.

func (DocumentInput) ApplyTo

func (in DocumentInput) ApplyTo(doc *Document) error

ApplyTo merges in into doc.

type Host

type Host struct {
	ID                   string `json:"id"`
	Name                 string `json:"name"`
	Description          string `json:"description,omitempty"`
	Host                 string `json:"host"`
	Port                 int    `json:"port"`
	Username             string `json:"username,omitempty"`
	AuthType             string `json:"authType"`
	Password             string `json:"password,omitempty"`
	PrivateKey           string `json:"privateKey,omitempty"`
	PrivateKeyPath       string `json:"privateKeyPath,omitempty"`
	PrivateKeyPassphrase string `json:"privateKeyPassphrase,omitempty"`
	Proxy                Proxy  `json:"proxy"`
}

Host is one stored SSH host, secrets included. It never leaves the backend as is: Public is the projection clients see.

func Apply

func Apply(stored Host, in HostInput) (Host, error)

Apply merges in into stored (the zero Host when the id is new) and validates the result.

func PutHost

func PutHost(doc *Document, in HostInput) (Host, error)

PutHost adds or replaces the host in.ID.

func (Host) Address

func (h Host) Address() string

Address is the host:port to dial, IPv6 literals bracketed.

func (Host) ConnectionFingerprint

func (h Host) ConnectionFingerprint() string

ConnectionFingerprint is connectionFingerprint for other packages; it is an opaque value that includes secrets and must never be shown or logged.

func (Host) Credential

func (h Host) Credential() string

Credential reports whether connecting needs nothing from the user (saved), is impossible until credentials are stored (missing), or needs the user to answer the server's prompts (interactive).

func (Host) Endpoint

func (h Host) Endpoint() string

Endpoint is user@host:port.

func (Host) Label

func (h Host) Label() string

Label is the name to show for the host.

type HostInput

type HostInput struct {
	ID                        string      `json:"id"`
	Name                      string      `json:"name"`
	Description               string      `json:"description,omitempty"`
	Host                      string      `json:"host"`
	Port                      PortValue   `json:"port,omitempty"`
	Username                  string      `json:"username,omitempty"`
	AuthType                  string      `json:"authType,omitempty"`
	Password                  string      `json:"password,omitempty"`
	ClearPassword             bool        `json:"clearPassword,omitempty"`
	PrivateKey                string      `json:"privateKey,omitempty"`
	ClearPrivateKey           bool        `json:"clearPrivateKey,omitempty"`
	PrivateKeyPath            string      `json:"privateKeyPath,omitempty"`
	PrivateKeyPassphrase      string      `json:"privateKeyPassphrase,omitempty"`
	ClearPrivateKeyPassphrase bool        `json:"clearPrivateKeyPassphrase,omitempty"`
	Proxy                     *ProxyInput `json:"proxy,omitempty"`

	PasswordConfigured             any `json:"passwordConfigured,omitempty"`
	PrivateKeyConfigured           any `json:"privateKeyConfigured,omitempty"`
	PrivateKeyPassphraseConfigured any `json:"privateKeyPassphraseConfigured,omitempty"`
	Credential                     any `json:"credential,omitempty"`
	HostKeys                       any `json:"hostKeys,omitempty"`
}

HostInput is a host as a client sends it. Secret fields follow the provider API key rules: empty keeps the stored value, a value replaces it, and the matching clear flag removes it. The "...Configured", credential and hostKeys fields GET returns are accepted and ignored, so a client can send back what it read.

type HostKeyStatus

type HostKeyStatus int

HostKeyStatus is how a presented host key compares with known_hosts.

const (
	// HostKeyTrusted: known_hosts has this key for the host.
	HostKeyTrusted HostKeyStatus = iota
	// HostKeyUnknown: known_hosts has no key for the host.
	HostKeyUnknown
	// HostKeyChanged: known_hosts has other keys for the host, or the key is
	// revoked.
	HostKeyChanged
)

type KnownHosts

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

KnownHosts is K-brain's own known_hosts file (OpenSSH format). It is never the user's ~/.ssh/known_hosts: K-brain trusts only keys the user accepted through K-brain.

func NewKnownHosts

func NewKnownHosts(path string) *KnownHosts

NewKnownHosts uses the file at path.

func (*KnownHosts) Add

func (k *KnownHosts) Add(address string, key ssh.PublicKey) error

Add trusts key for address.

func (*KnownHosts) Algorithms

func (k *KnownHosts) Algorithms(address string) []string

Algorithms lists the host key algorithms to offer for address so the server presents a key of a stored type; nil when none is stored.

func (*KnownHosts) Check

func (k *KnownHosts) Check(address string, key ssh.PublicKey) (HostKeyStatus, []KnownKey, error)

Check compares key, presented by address (host:port), with the file. For HostKeyChanged, known lists the keys stored for the host.

func (*KnownHosts) Keys

func (k *KnownHosts) Keys(address string) []KnownKey

Keys lists the keys stored for address.

func (*KnownHosts) Path

func (k *KnownHosts) Path() string

Path is the file's location.

func (*KnownHosts) Public

func (k *KnownHosts) Public(h Host) PublicHost

Public projects h for clients.

func (*KnownHosts) Remove

func (k *KnownHosts) Remove(address string) (int, error)

Remove forgets every key stored for address, so the next connection asks again. It is how a user re-trusts a host whose key changed.

type KnownKey

type KnownKey struct {
	Algorithm   string `json:"algorithm"`
	Fingerprint string `json:"fingerprint"`
}

KnownKey describes a stored host key without its bytes.

func Describe

func Describe(key ssh.PublicKey) KnownKey

Describe returns the algorithm and SHA256 fingerprint of key.

type PortValue

type PortValue int

PortValue accepts a port as a JSON number, a numeric string, "" or null.

func (*PortValue) UnmarshalJSON

func (p *PortValue) UnmarshalJSON(data []byte) error

type Proxy

type Proxy struct {
	// Type is "socks5" (default) or "http"; a scheme in URL wins.
	Type           string `json:"type"`
	URL            string `json:"url,omitempty"`
	Port           int    `json:"port,omitempty"`
	Username       string `json:"username,omitempty"`
	Password       string `json:"password,omitempty"`
	UseSystemProxy bool   `json:"useSystemProxy,omitempty"`
}

Proxy is the optional proxy a host is reached through.

func (Proxy) Configured

func (p Proxy) Configured() bool

Configured reports whether a proxy is set up (LiveAgent's rule).

type ProxyInput

type ProxyInput struct {
	Type               string    `json:"type,omitempty"`
	URL                string    `json:"url,omitempty"`
	Port               PortValue `json:"port,omitempty"`
	Username           string    `json:"username,omitempty"`
	Password           string    `json:"password,omitempty"`
	ClearPassword      bool      `json:"clearPassword,omitempty"`
	UseSystemProxy     bool      `json:"useSystemProxy,omitempty"`
	PasswordConfigured any       `json:"passwordConfigured,omitempty"`
}

ProxyInput is a host's proxy as a client sends it; Password follows the secret rules of HostInput.

type PublicDocument

type PublicDocument struct {
	Revision                uint64              `json:"revision"`
	Hosts                   []PublicHost        `json:"hosts"`
	ProjectHostAssociations map[string][]string `json:"projectHostAssociations"`
	KnownHostsPath          string              `json:"knownHostsPath"`
}

PublicDocument is the body of GET /v1/settings/ssh.

type PublicHost

type PublicHost struct {
	ID                             string      `json:"id"`
	Name                           string      `json:"name"`
	Description                    string      `json:"description"`
	Host                           string      `json:"host"`
	Port                           int         `json:"port"`
	Username                       string      `json:"username"`
	AuthType                       string      `json:"authType"`
	Password                       string      `json:"password"`
	PasswordConfigured             bool        `json:"passwordConfigured"`
	PrivateKey                     string      `json:"privateKey"`
	PrivateKeyPath                 string      `json:"privateKeyPath"`
	PrivateKeyConfigured           bool        `json:"privateKeyConfigured"`
	PrivateKeyPassphrase           string      `json:"privateKeyPassphrase"`
	PrivateKeyPassphraseConfigured bool        `json:"privateKeyPassphraseConfigured"`
	Proxy                          PublicProxy `json:"proxy"`
	Credential                     string      `json:"credential"`
	HostKeys                       []KnownKey  `json:"hostKeys"`
}

PublicHost is a host as GET /v1/settings/ssh returns it: LiveAgent's SshHostConfig shape with every secret blanked and reported through its "...Configured" flag, plus credential and the stored host keys.

type PublicProxy

type PublicProxy struct {
	Type               string `json:"type"`
	URL                string `json:"url"`
	Port               int    `json:"port"`
	Username           string `json:"username"`
	Password           string `json:"password"`
	PasswordConfigured bool   `json:"passwordConfigured"`
	UseSystemProxy     bool   `json:"useSystemProxy"`
}

PublicProxy is a host's proxy with its password blanked.

type Store

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

Store holds the hosts document and its file.

func Open

func Open(dir string) (*Store, error)

Open loads (or starts) the store in dir.

func (*Store) HasProjectHosts

func (s *Store) HasProjectHosts(project string) bool

HasProjectHosts reports whether project has any associated host.

func (*Store) Host

func (s *Store) Host(id string) (Host, bool)

Host returns one stored host.

func (*Store) KnownHosts

func (s *Store) KnownHosts() *KnownHosts

KnownHosts is the store's known_hosts file.

func (*Store) ProjectHosts

func (s *Store) ProjectHosts(project string) []Host

ProjectHosts returns the stored hosts associated with the project whose path (or key) is project, in association order.

func (*Store) Public

func (s *Store) Public() PublicDocument

Public projects the whole store for clients.

func (*Store) Revision

func (s *Store) Revision() uint64

Revision increases with every saved change.

func (*Store) Snapshot

func (s *Store) Snapshot() Document

Snapshot returns a copy of the stored document, secrets included.

func (*Store) Update

func (s *Store) Update(base uint64, fn func(*Document) error) (Document, uint64, error)

Update applies fn to a copy of the document and saves the result. base, if non-zero, must be the current revision. fn's error is returned as is.

Jump to

Keyboard shortcuts

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