Add :key and :key_path SSH auth options with custom key callback

Support passing a private key directly as a PEM string (:key) or
as a file path (:key_path), in addition to the existing :user_dir
and :password options. Uses a custom ssh_client_key_api callback
module to decode and provide keys to Erlang's :ssh.

Also add SSH provider example to README.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

README.md

@@ -47,7 +47,21 @@ config :terrarium,
   ]
 ```
 
-For development, you can use the built-in local provider:
+Connect to an existing machine via SSH:
+
+```elixir
+config :terrarium,
+  default: :server,
+  providers: [
+    server: {Terrarium.Providers.SSH,
+      host: "dev.example.com",
+      user: "deploy",
+      key: System.fetch_env!("SSH_PRIVATE_KEY")
+    }
+  ]
+```
+
+For development, use the built-in local provider:
 
 ```elixir
 # config/dev.exs

lib/terrarium/providers/ssh.ex

@@ -25,14 +25,29 @@ defmodule Terrarium.Providers.SSH do
   - `:port` — SSH port (default: `22`)
   - `:password` — password for authentication
   - `:user_dir` — directory containing SSH keys (default: `~/.ssh`)
+  - `:key` — private key as a PEM string (e.g., from an env var)
+  - `:key_path` — path to a specific private key file
   - `:connect_timeout` — connection timeout in milliseconds (default: `10_000`)
   - `:cwd` — default working directory on the remote host (default: `"/"`)
 
   ## Authentication
 
-  Supports password and key-based authentication. For key-based auth, place
-  your keys (`id_rsa`, `id_ed25519`, etc.) in the `:user_dir` directory.
-  The `:ssh` module discovers them automatically.
+  Supports three authentication methods:
+
+  - **Password** — `:password` option
+  - **Key directory** — `:user_dir` option, auto-discovers keys in the directory
+  - **Specific key** — `:key` (PEM string) or `:key_path` (file path)
+
+  ### Examples
+
+      # Password auth
+      {Terrarium.Providers.SSH, host: "example.com", user: "deploy", password: "secret"}
+
+      # Key from a file
+      {Terrarium.Providers.SSH, host: "example.com", user: "deploy", key_path: "~/.ssh/id_ed25519"}
+
+      # Key from an environment variable
+      {Terrarium.Providers.SSH, host: "example.com", user: "deploy", key: System.fetch_env!("SSH_PRIVATE_KEY")}
   """
 
   use Terrarium.Provider
@@ -56,7 +71,7 @@ defmodule Terrarium.Providers.SSH do
         user_interaction: false
       ]
       |> maybe_add(:password, opts)
-      |> maybe_add(:user_dir, opts)
+      |> maybe_add_key_opts(opts)
 
     case :ssh.connect(to_charlist(host), port, ssh_opts, connect_timeout) do
       {:ok, conn} ->
@@ -229,10 +244,19 @@ defmodule Terrarium.Providers.SSH do
     end
   end
 
-  defp maybe_add(ssh_opts, :user_dir, opts) do
-    case Keyword.fetch(opts, :user_dir) do
-      {:ok, dir} -> Keyword.put(ssh_opts, :user_dir, to_charlist(Path.expand(dir)))
-      :error -> ssh_opts
+  defp maybe_add_key_opts(ssh_opts, opts) do
+    cond do
+      Keyword.has_key?(opts, :key) ->
+        Keyword.put(ssh_opts, :key_cb, {Terrarium.Providers.SSH.KeyCb, key: opts[:key]})
+
+      Keyword.has_key?(opts, :key_path) ->
+        Keyword.put(ssh_opts, :key_cb, {Terrarium.Providers.SSH.KeyCb, key_path: opts[:key_path]})
+
+      Keyword.has_key?(opts, :user_dir) ->
+        Keyword.put(ssh_opts, :user_dir, to_charlist(Path.expand(opts[:user_dir])))
+
+      true ->
+        ssh_opts
     end
   end
 end

lib/terrarium/providers/ssh/key_cb.ex

@@ -0,0 +1,47 @@
+defmodule Terrarium.Providers.SSH.KeyCb do
+  @moduledoc false
+
+  # Custom SSH client key callback that accepts a private key as a PEM string
+  # or a file path, passed via key_cb_private.
+
+  @behaviour :ssh_client_key_api
+
+  @impl true
+  def is_host_key(_key, _host, _algorithm, _options), do: true
+
+  @impl true
+  def add_host_key(_host, _public_key, _options), do: :ok
+
+  @impl true
+  def user_key(_algorithm, options) do
+    key_cb_private = options[:key_cb_private] || []
+
+    cond do
+      pem = key_cb_private[:key] ->
+        decode_pem(pem)
+
+      path = key_cb_private[:key_path] ->
+        case File.read(Path.expand(path)) do
+          {:ok, pem} -> decode_pem(pem)
+          {:error, reason} -> {:error, reason}
+        end
+
+      true ->
+        {:error, :no_key_provided}
+    end
+  end
+
+  defp decode_pem(pem) do
+    case :public_key.pem_decode(pem) do
+      [entry | _] ->
+        {:ok, :public_key.pem_entry_decode(entry)}
+
+      [] ->
+        # OpenSSH format (ed25519, etc.) — OTP 25+
+        case :ssh_file.decode(pem, :openssh_key_v1) do
+          [{private_key, _attrs} | _] -> {:ok, private_key}
+          _ -> {:error, :pem_decode_failed}
+        end
+    end
+  end
+end