docs(troubleshooting): SSH publickey denial, and why guessing the username bans your IP

[cofade]

Captures an access failure that cost a working session, plus the incident lesson behind it.

The failure

ssh highfive returns Permission denied (publickey) even with the key correctly installed, because ~/.ssh/config pins only HostName — so OpenSSH sends the local account name as the login. The key is only half the credential; the login name is the other half, and it is not derivable from the key comment, your email, or the repo.

The trap is what comes next. Guessing the username (root, ubuntu, admin, …) trips the host's brute-force protection, and port 22 goes dead while https://highfive.schutera.com/ keeps returning 200. That asymmetry reads as "the SSH daemon is down", which invites more retries — the one action that cannot help.

This is not hypothetical: the repo owner's own ~/.ssh/config is currently in exactly this state, with # User ? commented out awaiting the login name.

What the section gives you

• ssh -G highfive as the opening move — prints the resolved config, sends zero packets, so it costs no auth attempt and still works while banned. It printed user wienh here, which is the whole bug in one line.
• A three-row diagnostic table with a control probe against a third host, because "web fine + port 22 dead" is equally consistent with your own network blocking outbound tcp/22 (corp LAN, VPN, hotel). Without the control you ask the owner to unban an address that was never banned.
• A safe config-writing block, and the placement rule that makes it work.
• The unban path, including what to do when the owner is the one locked out (fail2ban-client needs a shell on the host, so it's useless to them).

Plus a chapter-11 lessons entry — "probing prod with guessed usernames gets you banned, and the ban looks like an outage" is an incident, not a symptom→fix — and links from both places a reader is told to ssh (production-runbook.md, production-deployment.md).

Three defects review caught in my own draft

Worth listing, because they're all the same mistake: I verified the mechanism and not the outcome.

1. The config-writing block corrupted existing configs. Out-File -Append into a ~/.ssh/config with no trailing newline welds the stanza onto the last line:

    User olduserHost highfive

The stanza never registers, and HostName now carries three trailing tokens — a fatal parse error for every ssh invocation, not just this host. So the documented remedy escalated "I can't reach one server" into "ssh doesn't run at all", for someone already locked out. Now mirrors the Test-Path → notepad safe-write precedent this file already uses for .wslconfig.

2. The placeholder guard didn't hold. if (...) { throw } is a complete statement, so pasted into a console the throw prints red and execution continues into the write — producing User the-name-the-owner-gave-you, a config that looks fixed while sending a name indistinguishable from a guess. Reproduced in a real runspace. The check is now the first arm of the if/elseif/else that does the writing, so it cannot be stepped past.

3. "Retrying refreshes the ban timer" was false. Once banned, the firewall blocks the packet before sshd, so no auth failure is logged and nothing re-triggers the filter. The advice (stop retrying) was right; the reason was invented — and it contradicted my own blockquote three paragraphs above that declines to assert which mechanism this host even runs.

Also fixed: -o BatchMode=yes masked passphrase/host-key failures as Permission denied (publickey), byte-identical to the error being diagnosed; -ErrorAction SilentlyContinue does not suppress Select-String's PathNotFound in PS 5.1; Out-File throws on a missing .ssh dir; and an earlier Host * block silently beats a later Host highfive (verified with ssh -G -F: resolved to user git, not user realname).

Verification

Outcome-level, in a real runspace with correct paste semantics, against all three starting states:

Starting state	Result
Unedited placeholder	writes nothing (the throw version wrote it)
Fresh machine	creates config; ssh -G resolves user realname; ASCII, no BOM
Existing config, no trailing newline	left byte-identical

ssh -G and the Host * precedence were confirmed against real OpenSSH, and the Authenticating to … as '<user>' line shape against a live SSH endpoint. The maintainer's real ~/.ssh/config was confirmed untouched throughout. All five repo gate scripts and prettier are clean.

Docs-only — no code, no wire shapes, no UI, so ADR-014 / the Playwright rule don't apply.

🤖 Reviewed across two rounds with the repo's senior-reviewer gate.