ssh

Documentation

Overview

Package ssh provides SSH authentication and host key resolution for all SSH transports in StageFreight. It is the single authority for:

• SSH agent discovery (SSH_AUTH_SOCK)
• Private key file and in-memory resolution and parsing
• known_hosts host key verification

Both git-over-SSH (gitstate) and raw SSH execution (docker transport) depend on this package. No other package resolves SSH credentials or host keys.

Index

• func ResolveAuthMethods(keyPath string) ([]gossh.AuthMethod, error)
• func ResolveHostKeyCallback() (gossh.HostKeyCallback, error)
• func SignerFromData(data []byte) (gossh.Signer, error)
• func SignerFromDataEnv(data []byte) (gossh.Signer, error)
• func SignerFromDataWithPassphrase(data, passphrase []byte) (gossh.Signer, error)
• func SignerFromFile(keyPath string) (gossh.Signer, error)

Functions

func ResolveAuthMethods

func ResolveAuthMethods(keyPath string) ([]gossh.AuthMethod, error)

ResolveAuthMethods returns golang.org/x/crypto/ssh auth methods for raw SSH connections (remote command execution, file transfer, tunneling).

Resolution is exclusive — the first matching source wins entirely:

1. SSH_PRIVATE_KEY env var (PEM content; fails hard if set but invalid)
2. SSH_AUTH_SOCK agent
3. keyPath argument if non-empty
4. Standard key files: id_ed25519, id_ecdsa, id_rsa (first match wins)

SSH_PRIVATE_KEY is authoritative — when set, agent and filesystem are skipped, ensuring identical behavior across laptop, container, and CI.

Returns an error only when no method could be resolved at all. For git-over-SSH, callers should use gitstate.ResolveAuth instead.

func ResolveHostKeyCallback

func ResolveHostKeyCallback() (gossh.HostKeyCallback, error)

ResolveHostKeyCallback builds a gossh.HostKeyCallback for SSH host key verification.

Resolution order:

1. SSH_KNOWN_HOSTS_CONTENT env var (raw known_hosts lines — for containers/CI)
2. SSH_KNOWN_HOSTS env var (path to file — set by GitLab CI runner)
3. ~/.ssh/known_hosts
4. SSH_INSECURE_SKIP_HOST_KEY_CHECK=true (last resort — emits warning, never silent)

InsecureIgnoreHostKey is never used implicitly. If no known_hosts source is found and SSH_INSECURE_SKIP_HOST_KEY_CHECK is not set, an actionable error is returned.

This is the single source of truth for host key verification across all SSH transports in StageFreight (git, docker, and any future transports).

func SignerFromData

func SignerFromData(data []byte) (gossh.Signer, error)

SignerFromData parses an in-memory PEM private key and returns a gossh.Signer. Use SignerFromDataWithPassphrase for encrypted keys.

func SignerFromDataEnv

func SignerFromDataEnv(data []byte) (gossh.Signer, error)

SignerFromDataEnv parses a PEM private key, using SSH_PRIVATE_KEY_PASSPHRASE if set. Single source of truth for env-driven key parsing — used by both ResolveAuthMethods (raw SSH) and gitstate.ResolveAuth (go-git SSH transport).

func SignerFromDataWithPassphrase

func SignerFromDataWithPassphrase(data, passphrase []byte) (gossh.Signer, error)

SignerFromDataWithPassphrase parses an encrypted in-memory PEM private key using the supplied passphrase.

func SignerFromFile

func SignerFromFile(keyPath string) (gossh.Signer, error)

SignerFromFile parses an SSH private key file and returns a gossh.Signer. Returns os.ErrNotExist if the file is absent; other errors indicate parse failures.