FEAT: V2

[melbahja]

V2 Changelog

Breaking Changes

• Removed goph.Auth type and goph.Config struct.

  • Replaced by functional options passed directly to goph.New.

• Removed constructors: NewUnknown, NewConn.

  • Use goph.New(user, addr, opts...) with WithInsecureIgnoreHostKey() where needed.

• Removed auth constructor functions: goph.Password(), goph.Key(), goph.UseAgent().

  • Replaced by WithPassword, WithKeyFile, WithDefaultAgent, WithAgentSocket etc.

• Client.Config field removed.

  • *ssh.ClientConfig is now ephemeral: built in New, passed to options and dial helpers, then discarded. It is no longer stored on the connected Client.

• Renamed key auth options:

  • WithKey(file, passphrase) => WithKeyFile(file, passphrase)
  • WithRawKey(pem, passphrase) => WithKey(pem, passphrase)

• Renamed key parsing helpers:

  • GetSigner(file, passphrase) => ParseKeyFile(file, passphrase)
  • GetSignerForRawKey(key, passphrase) => ParseKey(key, passphrase)

New Features

• Functional options API.

  • WithPassword, WithKeyFile, WithKey, WithAgent, WithAgentSocket, WithDefaultAgent, WithSigner, WithAuth
  • WithPort, WithTimeout, WithKnownHosts, WithInsecureIgnoreHostKey, WithHostKeyCallback, WithBannerCallback, WithConfig
  • WithProxy, WithJump

• Dialer for reusable connections.

  • d := goph.NewDialer(opts...) then d.New(user, addr) for multiple hosts with shared defaults.

• SOCKS5 proxy authentication.

  • WithProxy can accepts URLs with embedded credentials: socks5://user:pass@host:port.

• Context-aware command cancellation.

  • RunContext and CommandContext accept context.Context.
  • Cancellation sends ssh.SIGINT to the remote session.

• goph.Dial.

  • goph.Dial(c *Client, config *ssh.ClientConfig) error for manual Client construction and custom ssh.ClientConfig.
  • Client now stores User; Dial defaults config.User to Client.User or the current OS user when empty.
  • Direct TCP dials now respect config.Timeout.

• Security fixes.

  • WithPassword no longer includes a keyboard-interactive fallback. Added standalone WithKeyboardInteractive(handler) that gives callers full control over each server prompt (password, OTP, 2FA, etc.).
  • Cmd.String warning now clearly states that Path and Args are not shell-escaped and that callers must sanitize untrusted input.

• Known-hosts helpers.

  • KnownHosts now documents that the file must exist.
  • New EnsureKnownHosts creates the file (and parent directory) if missing.
  • DefaultKnownHosts uses EnsureKnownHosts so first-time users no longer hit a file-read error when ~/.ssh/known_hosts is absent.

  Related Issues

  • resolves Is there a way to specify ssh options? #64
  • resolves Give precedence ~/.ssh/config file over $SSH_AUTH_SOCK + ability set custom SSH socket path #57
  • resolves how to access remote server via a tcp proxy? #56
  • resolves can support execute shell script file? #53
  • resolves Custom ssh port #29
  • resolves Add support to connect via ProxyJump option #22 (now y can even do proxy -> jump -> proxy -> host)
  • resolves support pkcs#11 and ms capi ? #16 (via WithSigner and external library)

  Example of usage of each issue solution will be referenced in docs.