Merge #421: feat: [#411] detect passphrase-protected SSH key and warn during create environment

e688a7c feat: [#411] detect passphrase-protected SSH key and warn during create environment (Jose Celano)
3a3c078 docs: [#411] add alternative detection approach and ADR task to spec (Jose Celano)

Pull request description:

  ## Summary

  Closes #411

  When a passphrase-protected SSH private key is configured in `ssh_credentials`, the deployer previously failed silently during `provision` with a misleading `Permission denied (publickey,password)` error. This PR adds an early non-blocking warning during `create environment` so users can make an informed decision before reaching `provision`.

  ## Changes

  ### Detection (`src/adapters/ssh/key_inspector.rs` — new module)

  - Moved passphrase detection out of `credentials.rs` into a dedicated `key_inspector` module (cleaner separation of concerns)
  - `is_passphrase_protected(path: &Path) -> bool` — best-effort heuristic:
    - Legacy PEM: checks for `BEGIN ENCRYPTED PRIVATE KEY` / `Proc-Type: 4,ENCRYPTED` header
    - OpenSSH format: base64-decodes the body and scans first 100 bytes for `bcrypt` KDF marker
  - Uses the `base64` crate (now a direct dependency; was already transitive at v0.22.1) instead of an inline decoder
  - 4 unit tests covering: unencrypted key, passphrase-protected key, missing file, legacy PEM header

  ### Warning (`src/presentation/cli/views/progress/mod.rs`, `handler.rs`)

  - Added `ProgressReporter::warn()` for advisory user-facing messages
  - `CreateEnvironmentCommandController::execute()` calls `warn_if_ssh_key_passphrase_protected()` after config load — emits a detailed warning with 3 resolution options but does **not** block environment creation

  ### Test fixture

  - `fixtures/testing_ed25519_encrypted` — real ed25519 key protected with passphrase `"password"`, used in unit tests

  ### ADR

  - `docs/decisions/ssh-key-passphrase-detection.md` — documents the byte inspection approach and why `ssh-keygen -y` probe was rejected

  ### Documentation

  - `docs/user-guide/ssh-keys.md` — new page covering SSH key requirements, 3 supported workflows, how to remove a passphrase, and security notes
  - `docs/user-guide/providers/hetzner.md` — added SSH Key Requirements section with warning callout
  - `docs/user-guide/commands/create.md` — added passphrase warning subsection in Troubleshooting
  - `docs/user-guide/README.md` — added SSH Keys subsection under Security with link

  ## Testing

  All pre-commit checks pass:
  - `cargo machete` ✅
  - `cargo run --bin linter all` (clippy stable + nightly, rustfmt, cspell, shellcheck, markdownlint, yamllint, taplo) ✅
  - `cargo test` (417 tests) ✅
  - `cargo doc` ✅
  - E2E infrastructure lifecycle tests ✅
  - E2E deployment workflow tests ✅

ACKs for top commit:
  josecelano:
    ACK e688a7c

Tree-SHA512: 9cd13240680cf1cd248c0b34f0e2df88b302a52823d92e9f8e5b7ad0976d57a47c475d3ed765b43dda66866f0d248f2d4d7b972a5ad76d36095087b4c65fb857

Author: josecelano

Cargo.toml

@@ -44,6 +44,7 @@ path = "src/bin/test_logging.rs"
 [dependencies]
 tokio = { version = "1.0", features = [ "full" ] }
 anyhow = "1.0"
+base64 = "0.22"
 chrono = { version = "0.4", features = [ "serde" ] }
 clap = { version = "4.0", features = [ "derive" ] }
 derive_more = { version = "2.1", features = [ "display", "from" ] }

docs/decisions/README.md

@@ -6,6 +6,7 @@ This directory contains architectural decision records for the Torrust Tracker D
 
 | Status        | Date       | Decision                                                                                                  | Summary                                                                                    |
 | ------------- | ---------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| ✅ Accepted   | 2026-04-07 | [SSH Key Passphrase Detection](./ssh-key-passphrase-detection.md)                                         | Detect passphrase-protected keys via byte inspection; reject ssh-keygen probe approach     |
 | ✅ Accepted   | 2026-02-26 | [SDK Package Naming](./sdk-package-naming.md)                                                             | Keep "SDK" name for packages/sdk — the modern API-wrapper meaning is industry-standard     |
 | ✅ Accepted   | 2026-02-24 | [SDK Presentation Layer Interface Design](./sdk-presentation-layer-interface-design.md)                   | Return () from SDK operations; no domain types or typestate pattern in the SDK public API  |
 | ✅ Accepted   | 2026-02-24 | [Docker Compose Local Validation Placement](./docker-compose-local-validation-placement.md)               | Validate rendered docker-compose.yml in the infrastructure generator, not the app layer    |

docs/decisions/ssh-key-passphrase-detection.md

@@ -0,0 +1,90 @@
+# Decision: SSH Key Passphrase Detection via Byte Inspection
+
+## Status
+
+✅ Accepted
+
+## Date
+
+2026-04-07
+
+## Context
+
+When a user configures a passphrase-protected SSH private key in `ssh_credentials`,
+the deployer fails silently during the `provision` step with a misleading
+`Permission denied (publickey,password)` error. The root cause — that the key is
+encrypted and cannot be decrypted without a passphrase in an unattended environment —
+is never surfaced.
+
+To give users an early, actionable warning, the `create environment` command needs to
+detect whether the configured private key is passphrase-protected before it runs the
+deployment workflow. Two approaches were considered.
+
+See also: [Issue #411](../../docs/issues/411-bug-ssh-key-passphrase-breaks-automated-deployment.md)
+
+## Decision
+
+Detect passphrase protection by reading and inspecting the raw bytes of the key file
+(**byte inspection**), implemented as a pure-Rust free function
+`is_passphrase_protected(path: &Path) -> bool` in
+`src/adapters/ssh/credentials.rs`.
+
+Detection rules:
+
+- **Legacy PEM format** (`PKCS#8` / traditional): the header line contains
+  `BEGIN ENCRYPTED PRIVATE KEY` or the `Proc-Type: 4,ENCRYPTED` header is present.
+- **OpenSSH format** (`-----BEGIN OPENSSH PRIVATE KEY-----`): the binary body
+  (base64-decoded) contains the byte sequence `bcrypt` within the first 100 bytes.
+  OpenSSH uses `bcrypt` as the KDF name when a passphrase is set; the KDF name is
+  `none` for unencrypted keys.
+
+The check is **best-effort**:
+
+- A false negative (encrypted key not detected) is acceptable — the warning is advisory.
+- A false positive (unencrypted key flagged) must be avoided — it would confuse users.
+- Any I/O or parse error returns `false` (no spurious warning).
+
+## Consequences
+
+**Positive**:
+
+- Pure Rust, zero new dependencies. No external process is spawned just for detection.
+- Fast: reads only the first ~150 bytes of the file (header + base64 start).
+- Works in any environment, including minimal Docker images where `ssh-keygen` may not
+  be present.
+- Handles both common key formats (legacy PEM, OpenSSH).
+
+**Negative / Risks**:
+
+- False-negative risk for exotic or future key formats (e.g., PKCS#1 passphrase-
+  protected RSA keys with `Proc-Type` elsewhere in the file). Acceptable per spec.
+- Requires maintaining a small inline base64 decoder (~25 lines) because no base64
+  crate is in the dependency list. The decoder is minimal but covers the standard
+  alphabet only; malformed base64 returns `false` rather than an error.
+
+## Alternatives Considered
+
+### `ssh-keygen -y` probe
+
+Spawn `ssh-keygen -y -f <key> < /dev/null`: this exits non-zero when the key is
+passphrase-protected, allowing detection via the exit code.
+
+**Rejected because**:
+
+- Requires `ssh-keygen` to be present at runtime. Docker images used in CI/CD may not
+  include it, making the check environment-dependent.
+- Spawns an external process with I/O redirection just for an advisory check — this
+  adds latency and error-handling complexity (exit codes must distinguish "encrypted"
+  from "file not found" or "unsupported format").
+- The byte-inspection approach is faster, self-contained, and sufficient for the
+  best-effort goal.
+
+## Related Decisions
+
+- [Validated Deserialization for Domain Types](./validated-deserialization-for-domain-types.md)
+
+## References
+
+- [Issue #411 spec](../issues/411-bug-ssh-key-passphrase-breaks-automated-deployment.md)
+- [OpenSSH key format](https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key)
+- Implementation: `src/adapters/ssh/credentials.rs`

docs/issues/411-bug-ssh-key-passphrase-breaks-automated-deployment.md

@@ -68,12 +68,47 @@ The reliable detection approach is to read the first line of the PEM file:
 - OpenSSH format: the body begins with `bcrypt` if passphrase-protected; the header
   alone is not sufficient — the first few bytes of the decoded body must be checked.
 
-The simplest robust approach in Rust is to read the raw bytes of the key file and check:
+### Detection Approaches Considered
+
+Two approaches were evaluated for detecting whether a key is passphrase-protected:
+
+#### Option A — Byte inspection (chosen)
+
+Read the raw bytes of the key file and check:
 
 - For legacy PEM: `ENCRYPTED` appears in the header
 - For OpenSSH format: after the base64-decoded body, the string `bcrypt` appears near
   the start (OpenSSH uses bcrypt KDF for passphrase derivation)
 
+|     |                                                                                 |
+| --- | ------------------------------------------------------------------------------- |
+| ✅  | Pure Rust, no external tools required                                           |
+| ✅  | Fast — reads only the first ~64 bytes of the file                               |
+| ✅  | Works in any environment, including minimal Docker images                       |
+| ✅  | No process spawning overhead                                                    |
+| ❌  | Must handle two PEM variants (legacy `ENCRYPTED` header, OpenSSH `bcrypt` body) |
+| ❌  | False-negative risk for exotic or future key formats (acceptable per spec)      |
+
+#### Option B — `ssh-keygen -y` probe
+
+Spawn `ssh-keygen -y -f <key> < /dev/null`: this command attempts to derive the public
+key from the private key and exits non-zero with a passphrase prompt when the key is
+encrypted.
+
+|     |                                                                                                     |
+| --- | --------------------------------------------------------------------------------------------------- |
+| ✅  | Handles all key formats transparently — no format-specific parsing                                  |
+| ✅  | Implementation is a single `std::process::Command` call                                             |
+| ❌  | Requires `ssh-keygen` to be present in the runtime environment                                      |
+| ❌  | Spawns an external process just for detection                                                       |
+| ❌  | Must distinguish "encrypted" from "file not found" / "unsupported format" via exit codes and stderr |
+| ❌  | Slower than reading a few bytes from a file                                                         |
+
+**Chosen approach**: Option A (byte inspection). The deployer already targets Docker
+containers where `ssh-keygen` may not be installed, and the detection is best-effort
+(a missed warning is acceptable — a false positive is not). An ADR documents this
+choice in full (see Implementation Plan).
+
 The check only needs to be a best-effort heuristic — it is used to emit a warning, not
 to block the user. A false negative (missing the warning) is acceptable; a false
 positive (warning for an unencrypted key) would be confusing and should be avoided.
@@ -200,14 +235,22 @@ configured private key appears to be passphrase-protected.
       with and without passphrase if available, or by constructing the minimal PEM
       structure in the test)
 
-### Phase 2: Documentation
+### Phase 2: ADR
+
+- [ ] Create `docs/decisions/XXX-ssh-key-passphrase-detection.md` documenting:
+  - Why byte inspection was chosen over the `ssh-keygen -y` probe
+  - Pros and cons of each approach
+  - Consequences and limitations (best-effort, false-negative acceptable)
+- [ ] Register the new ADR in `docs/decisions/README.md`
+
+### Phase 3: Documentation
 
 - [ ] Create `docs/user-guide/ssh-keys.md` covering all workflows and security notes
 - [ ] Update `docs/user-guide/providers/hetzner.md` with an SSH key requirements note
 - [ ] Update `docs/user-guide/commands/create.md` to mention the passphrase warning
 - [ ] Update `docs/user-guide/README.md` to link to the new `ssh-keys.md` page
 
-### Phase 3: Linting and pre-commit
+### Phase 4: Linting and pre-commit
 
 - [ ] Run linters: `cargo run --bin linter all`
 - [ ] Run pre-commit: `./scripts/pre-commit.sh`

docs/user-guide/README.md

@@ -388,6 +388,13 @@ See individual service guides for detailed configuration options and verificatio
 - Production security checklist
 - Security incident response
 
+### SSH Keys
+
+The deployer uses SSH for all remote operations (`provision`, `configure`, `release`, `run`).
+Automated deployments (Docker, CI/CD) require a passphrase-free key or SSH agent forwarding.
+
+**[📖 SSH Keys Guide →](ssh-keys.md)**
+
 ### Logging Configuration
 
 Control logging output with command-line options:

docs/user-guide/commands/create.md

@@ -833,6 +833,32 @@ ssh-keygen -t rsa -b 4096 -f ~/.ssh/deployer_key
 "public_key_path": "~/.ssh/deployer_key.pub"
 ```
 
+### Passphrase-Protected SSH Key Warning
+
+**During `create environment` you may see**:
+
+```text
+⚠️  SSH private key appears to be passphrase-protected.
+  Key: /home/you/.ssh/torrust_key
+
+  Automated deployment (e.g. Docker, CI/CD) requires an SSH key that can be
+  used without interactive input. A passphrase-protected key will cause the
+  `provision` step to fail with "Permission denied" unless one of the
+  following is arranged: …
+```
+
+This is a **warning, not an error** — the environment is created normally. The warning
+means the configured key is encrypted and may not work in automated contexts (Docker,
+CI/CD) without an SSH agent.
+
+**Resolution options**:
+
+1. Remove the passphrase: `ssh-keygen -p -f /path/to/your/key`
+2. Forward your SSH agent socket into the Docker container.
+3. Use a separate passphrase-free deployment key.
+
+See the [SSH Keys Guide](../ssh-keys.md) for full details on all three workflows.
+
 ### Environment Already Exists
 
 **Problem**: `Environment 'my-env' already exists`

docs/user-guide/providers/hetzner.md

@@ -145,6 +145,32 @@ cat /var/log/cloud-init-output.log
 4. **Regular updates** - Keep server packages updated
 5. **Disable root SSH access** - For production, see [SSH Root Access Guide](../../security/ssh-root-access-hetzner.md)
 
+## SSH Key Requirements
+
+> ⚠️ **Docker deployments require a passphrase-free SSH key (or SSH agent forwarding).**
+
+When you run the deployer inside a Docker container (the recommended approach for
+Hetzner), there is no SSH agent and no interactive terminal. A passphrase-protected
+private key will cause the `provision` step to fail with
+`Permission denied (publickey,password)`.
+
+**Options**:
+
+1. **Remove the passphrase** (recommended for dedicated deployment keys):
+
+   ```bash
+   ssh-keygen -p -f ~/.ssh/your_deployment_key
+   # Press Enter twice for an empty new passphrase
+   ```
+
+2. **Forward your SSH agent** into the container (see [SSH Keys Guide](../ssh-keys.md#workflow-2--passphrase-protected-key-with-ssh-agent-forwarding-into-docker)).
+
+The `create environment` command will warn you if it detects a passphrase-protected key
+so you can resolve this before reaching `provision`.
+
+For more detail on generating keys, removing passphrases, and security considerations,
+see the [SSH Keys Guide](../ssh-keys.md).
+
 ## SSH Key Behavior
 
 Hetzner deployments configure SSH access through two mechanisms: