Almost every user new to SSH hits this wall:

WARNING: UNPROTECTED PRIVATE KEY FILE!
Permissions 0644 for '/Users/.../id_rsa.pem' are too open.
This private key will be ignored.

They placed the key in ~/.ssh/, entered the path into the SSH settings, and clicked Connect — only to see this. The fix is a single command (chmod 600 ~/.ssh/id_rsa.pem), which is obvious to anyone familiar with SSH but the biggest stumbling block for users who don't open a terminal.

Here's the design behind solving this inside the app — diagnose, confirm, then auto-fix — and how the phases broke out.

Why OpenSSH demands 0600

OpenSSH (and paramiko, which mirrors the same check internally) refuses to load a private key unless permissions are owner read/write only (0600).

The reason is straightforward: if anyone else can read your private key, it's effectively already compromised. Read access to the file is equivalent to "I have one half of the key pair," and someone with that file can ssh-add it elsewhere and reach every server that trusts the matching public key.

It's a safety net on OpenSSH's side to prevent "accidentally running with permissive permissions." The trap is that when you generate or receive a key, the default is often 0644 (world-readable).

The straightforward fix — chmod 600

One terminal line:

chmod 600 ~/.ssh/id_rsa.pem

That satisfies OpenSSH's strict mode and the connection works. Familiar territory for anyone with SSH experience.

But within our user base, there's a real cohort — agencies, IT operators — who have never opened a terminal. The macOS flow ("open Spotlight, type 'Terminal,' launch it, type a command") is heavier psychologically than it looks, and it shows up directly as a class of support tickets.

Diagnose → confirm → auto-fix, inside the app

So now, the moment the user enters a key path, the app inspects permissions from the inside. If they're too permissive, it pops a "fix permissions?" dialog. The user clicks the button, and the app runs the chmod 600 equivalent in the background.

def diagnose_ssh_key(path: str) -> dict:
    """
    {
      "permission_ok": bool,
      "current_mode": "0644",
      "target_mode":  "0600",
      "platform":     "macOS" | "Windows" | "Linux",
      "fix_safe":     bool,  # False on shared paths or non-owned files
    }
    """
    ...

Windows takes a different code path because OpenSSH's strict mode there requires "only the current user has ACL" rather than the Unix-style 0600. The fix runs icacls to remove other ACL entries. platform dispatch makes this transparent to the caller.

Hybrid: Phase 1 (post-failure) + Phase 2 (preventive)

The fix needs an obvious trigger point. We use two:

Phase 1 — post-failure recovery
Press "Test connection" → SSH fails with permission_error → the error UI dynamically adds a "🔧 Fix and retry" button → clicking it runs chmod 600 and retries the connection.

Phase 2 — pre-connection prevention
Press "Test connection" → first hit /api/diagnose_ssh_key → if permissions are loose, show a warning dialog with "🔧 Fix, then connect" and "Connect as-is" buttons.

Phase 1 alone leaves the user with one initial failure. Phase 2 alone separates diagnosis from connection-testing, which feels redundant. Running both ends up smoothest in practice — Phase 2 catches things ahead of time, Phase 1 catches the ones Phase 2 missed.

Phase 3 (auto-fix at startup) — deliberately not adopted

There was a Phase 3 idea: "Why not detect at app startup and auto-fix without a prompt?" We chose not to.

The reason is the risk of misidentifying intentionally permissive keys. Some SSH workflows share a private key across multiple users; in those, group-readable (0640, for instance) is intentional. If the app silently tightens those to 0600, other users on the machine lose access.

We landed on a design principle: modification actions always require an explicit user button press.

The "automatic vs. consent" balance is a tricky line between UX improvement and security. Our current conclusion: modifying-side operations always wait for human consent.

Takeaway — UX walls often dissolve from the inside

"Just type a command in the terminal" reads as obvious to engineers, but for the non-terminal cohort it's the single largest psychological barrier. Building a UX that diagnoses inside the app — "this is what's wrong, this is what'd fix it" — and runs the fix only with consent has noticeably reduced SSH-related support volume.

A similar pattern shows up elsewhere — the seven-format SSH private-key compat loader is another case of "absorb it inside the app so the user doesn't have to do anything."

Modify carefully (only with consent); diagnose and propose generously. That balance feels like the right landing point for SSH UX that includes users uncomfortable with terminals.