Import a Hetzner Cloud project's servers, and forget the token that read it

An estate on Hetzner is already described somewhere: the project lists every
server, its addresses, its plan and where it runs. Getting that into a keychain
meant copying forty addresses out of a browser by hand, which is the same work
the ssh_config importer exists to remove for the machines described in a file.

◆ A WIZARD RATHER THAN A SCREEN, AND THE DIFFERENCE IS WHAT EACH STEP COSTS.

ImportScreen reads a file that is already on this machine, so it scans on open
and shows a list. This cannot: it needs a credential that has to be made in
another company's console first, and then it makes a request over the internet.
Those are two moments rather than one, and a screen that mixed the token box in
with the list would ask for the credential again every time somebody came back
to look at the list.

So three steps — token, choose, done — and the first two write nothing. Step two
carries one address choice, one login user and one port for the whole import,
because an estate is reached the same way throughout and a per-server dropdown
would be forty answers to one question.

◆ THE TOKEN IS USED ONCE AND CLEARED, INCLUDING WHEN IT WORKED.

The half worth stating is the success path. Clearing only on failure would leave
a credential capable of listing somebody's whole estate sitting in a text box for
as long as they spend reading forty rows, which is the longest anybody stands on
this screen. Nothing writes it to the vault, to settings or to a log, and
reopening the wizard restarts at step one rather than resuming — a resumed step
two would be a list nothing on screen has the means to refresh, going on looking
current for as long as the application stays open.

Read is the only permission it needs and the note above the box says so: a
Read & Write token would work identically here and would be a credential capable
of deleting the estate, pasted in for no gain. The note also says a token belongs
to one project — there is no API call that will say which, and none that lists
the others — so an account with four projects runs this four times. Without that
sentence the wizard looks like it lost most of the estate.

◆ THE ADDRESS IS A CHOICE, AND TWO OF THE THREE FALL BACK WHERE THE THIRD MUST NOT.

Public IPv4 and public IPv6 fall back to each other: the same machine over the
same internet, so the worst case is a route nobody picked, and the row says which.
Private does not fall back at all. A server on no private network is simply not
importable under that choice — its tickbox is disabled, and neither direction of
the header's tick-all can reach it — because falling back would put an address on
the open internet into a bookmark that was asked to stay off it.

IPv6 needs saying twice over. Hetzner routes a whole /64 and the API reports the
network, which nothing can dial; the address a stock image answers on is the
first one in it. That is a convention of Hetzner's own images rather than a fact
the API stated, so every use of it carries a warning on the row and in the stored
note, and it is computed by setting the low byte rather than by string surgery on
the prefix. It is not an edge case either — IPv4 is billed separately now and a
project built since then can be entirely IPv6-only.

◆ NOTHING IMPORTED HERE AUTHENTICATES, AND THAT IS SAID BEFORE THE BUTTON.

Hetzner has never held the private half of an SSH key. The API will name a
project's keys and hand over their public halves; there is no private half to
bring. So every host arrives bound to nothing and asks for a password until
somebody points it at a key already in the keychain — the same shape an
ssh_config import has with its key tick off, and stated above the button on the
same reasoning: somebody who is not told will conclude the import was broken.

What the note keeps is what does not go stale — the id, the plan, the location,
the image, the labels. The power state is a column and never a note: "running"
about a machine somebody switched off last March is worse than no note.

◆ WHERE IT LIVES: TWO FLAGS OVER ONE CONTENT COLUMN.

Drawn over the Preferences page inside settings mode exactly as ImportScreen is,
with SettingsNav unmoved and the titlebar offering "Back to preferences".
IsHetznerImportOpen is a second flag rather than a "which importer" enum, because
they are two independent facts about the content column and a single value would
need a "neither" member IsImportOpen already expresses; what keeps them from both
being true is that every path that opens one closes the other. The titlebar and
the Preferences page ask IsImporterOpen, which is written against both.

Preferences grows a second importer row beside the first rather than one row that
asks "from where?", which would put a question in front of the far more common
answer.

◆ WHAT IS NOT HERE.

Hetzner's Robot — dedicated servers and Storage Boxes — is a different API behind
a different credential, and nothing in this touches it. Said on the Preferences
row and on the token step rather than left to be discovered by an account that
has both.

And there is no phone layout. This one would work on Android, unlike the
ssh_config importer beside it: it is a token and a network request, the view
model is shared already, and scoped storage has nothing to do with it. What is
missing is a screen — the desktop draws a five-column table, and the phone
version of that is a different layout rather than the same one narrower. Recorded
in android-port.md and on the phone's own Preferences screen, because the note
there previously read as though no import of any kind could work.

◆ TESTS, AND WHAT IS LEFT FOR A PERSON.

HetznerCloudClientTests is 16 cases over the shapes the API actually returns,
against a stubbed HttpMessageHandler: paging followed, the token in a header and
never a query string, a refused token distinguished from a fault at Hetzner's
end, a token with a line break refused before anything is sent, the /64, the
private-network asymmetry, and a server the API described without a name.

ShellFlowTests.Hetzner.cs is 11 more against this fixture's real vault, real
cache and real server — split into a file of its own, as FakeVaultServer keeps
its team endpoints. What they establish beyond the reader's own suite is the half
it cannot reach: that reading stores nothing, that importing goes through the
ordinary create-and-push path and lands on the server with nothing pressing Sync,
that a server the keychain already has arrives unticked, and that the token does
not outlive the request.

Two layout cases measure both steps against the same content budget every other
settings page gets, which is also what proves the markup binds to names that
exist.

Manual checks 2.11a–2.11d are what no test in this repository can do, because
there is no account, no token and no network in the ordinary suite: a real
project listed against the real console, a wrong token, the private choice, and
what an imported host does when you connect to it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

tests/DodoSSH.Client.App.Tests/ShellFlowTests.Hetzner.cs

@@ -0,0 +1,445 @@
+using System.Net;
+using System.Text;
+using DodoSSH.Client.Import;
+using DodoSSH.Client.Shell.ViewModels;
+
+namespace DodoSSH.Client.App.Tests;
+
+/// <summary>
+/// The Hetzner Cloud wizard, from a token to hosts on the server.
+/// </summary>
+/// <remarks>
+/// <para>
+/// What this establishes beyond <c>HetznerCloudClientTests</c> is the half that suite cannot reach: that
+/// reading a project stores nothing, that importing goes through the ordinary create-and-push path every
+/// other write uses, that a server the keychain already points at arrives unticked rather than silently
+/// duplicated, and that the token does not outlive the request it was typed for.
+/// </para>
+/// <para>
+/// Hetzner is a stubbed <c>HttpMessageHandler</c>. Everything else — the vault, the cache, the server — is
+/// this fixture's real one, which is the point: the assertion that matters most is that the imported hosts
+/// reached the server without anything pressing Sync.
+/// </para>
+/// </remarks>
+public sealed partial class ShellFlowTests
+{
+    private const string HetznerToken =
+        "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789";
+
+    /// <summary>
+    /// The whole wizard.
+    /// </summary>
+    /// <remarks>
+    /// One server already in the keychain and one not, so the two halves of the default are both exercised:
+    /// the new one arrives ticked, the known one does not, and only the ticked one is stored.
+    /// </remarks>
+    [Fact]
+    public async Task ImportingFromHetzner_ShowsTheProjectFirstAndThenStoresWhatWasTicked()
+    {
+        await UnlockedAsync();
+        var vault = shell.Vault!;
+
+        // db.internal:deploy is what AddHostAsync creates, so the first server is one the keychain has.
+        await AddHostAsync(vault, "prod-db");
+
+        var wizard = Wizard(Project("""
+            {
+              "id": 1,
+              "name": "already-here",
+              "status": "running",
+              "public_net": { "ipv4": { "ip": "db.internal" } }
+            }
+            """,
+            """
+            {
+              "id": 2,
+              "name": "web-01",
+              "status": "running",
+              "public_net": { "ipv4": { "ip": "203.0.113.10" } },
+              "server_type": { "name": "cx22" },
+              "datacenter": { "name": "fsn1-dc14", "location": { "name": "fsn1", "city": "Falkenstein", "country": "DE" } },
+              "image": { "name": "ubuntu-24.04" }
+            }
+            """));
+
+        wizard.Step.ShouldBe(HetznerImportStep.Token, "it opens on the box, having sent nothing");
+
+        wizard.Token = HetznerToken;
+        wizard.Username = "deploy";
+
+        await wizard.ScanCommand.ExecuteAsync(null);
+
+        wizard.Step.ShouldBe(HetznerImportStep.Choose);
+        wizard.Rows.Count.ShouldBe(2);
+        vault.Hosts.Count.ShouldBe(1, "reading the project stores nothing");
+
+        var known = wizard.Rows.Single(row => string.Equals(row.Name, "already-here", StringComparison.Ordinal));
+
+        known.AlreadyPresent.ShouldBeTrue("it points at a machine the keychain already has");
+        known.IsSelected.ShouldBeFalse("a duplicate takes a click rather than being the default");
+
+        var fresh = wizard.Rows.Single(row => string.Equals(row.Name, "web-01", StringComparison.Ordinal));
+
+        fresh.IsSelected.ShouldBeTrue();
+        fresh.Address.ShouldBe("203.0.113.10");
+
+        await wizard.ImportCommand.ExecuteAsync(null);
+
+        wizard.Step.ShouldBe(HetznerImportStep.Done);
+
+        var imported = vault.Hosts.Single(row => string.Equals(row.Label, "web-01", StringComparison.Ordinal));
+
+        imported.Address.ShouldBe("deploy@203.0.113.10:22");
+        imported.Host.SshKeyId.ShouldBeNull("Hetzner has no private key to hand over");
+        imported.Host.Notes.ShouldNotBeNull().ShouldContain("cx22");
+
+        vault.Hosts.Count.ShouldBe(2, "only the ticked one was stored");
+
+        // Through the ordinary path, which is the point of routing it through the vault: it reached the
+        // server without anything pressing Sync.
+        server.LiveRowCount.ShouldBe(2);
+    }
+
+    /// <summary>
+    /// The token does not outlive the request it was typed for.
+    /// </summary>
+    /// <remarks>
+    /// This is the whole of what makes pasting a credential capable of listing somebody's estate into a text
+    /// box acceptable: it is used once and dropped. Asserted on the success path deliberately — a wizard
+    /// that cleared the box only when something went wrong would leave the token sitting there for the
+    /// entire time somebody spends reading a list of forty servers.
+    /// </remarks>
+    [Fact]
+    public async Task TheTokenIsForgottenAsSoonAsTheProjectHasBeenRead()
+    {
+        await UnlockedAsync();
+
+        var wizard = Wizard(Project(WebServer));
+
+        wizard.Token = HetznerToken;
+
+        await wizard.ScanCommand.ExecuteAsync(null);
+
+        wizard.Token.ShouldBeEmpty();
+        wizard.Rows.ShouldHaveSingleItem();
+    }
+
+    /// <remarks>
+    /// A refused token is the failure this meets most often, and the recovery is to type a different one —
+    /// so it stays on the step that has the box, with a message that says where tokens come from.
+    /// </remarks>
+    [Fact]
+    public async Task ARefusedToken_StaysOnTheTokenStepAndStoresNothing()
+    {
+        await UnlockedAsync();
+
+        var wizard = Wizard(new StubHetznerResponse(
+            HttpStatusCode.Unauthorized,
+            """{ "error": { "code": "unauthorized", "message": "unable to authenticate" } }"""));
+
+        wizard.Token = HetznerToken;
+
+        await wizard.ScanCommand.ExecuteAsync(null);
+
+        wizard.Step.ShouldBe(HetznerImportStep.Token);
+        wizard.Status.ShouldContain("API tokens");
+        wizard.Rows.ShouldBeEmpty();
+        wizard.Token.ShouldBeEmpty("a refused token is retyped rather than corrected in place");
+        shell.Vault!.Hosts.ShouldBeEmpty();
+    }
+
+    /// <remarks>
+    /// An empty project is a correct answer to a correct token, so it is not an error — and it is not a step
+    /// forward either, because a list screen with nothing on it says less than the sentence does.
+    /// </remarks>
+    [Fact]
+    public async Task AnEmptyProject_SaysSoWithoutMovingOn()
+    {
+        await UnlockedAsync();
+
+        var wizard = Wizard(Project());
+
+        wizard.Token = HetznerToken;
+
+        await wizard.ScanCommand.ExecuteAsync(null);
+
+        wizard.Step.ShouldBe(HetznerImportStep.Token);
+        wizard.Status.ShouldContain("no servers");
+    }
+
+    /// <summary>
+    /// Choosing the private network does not quietly put a public address in the keychain.
+    /// </summary>
+    /// <remarks>
+    /// The one asymmetry in how addresses resolve, and the reason for it: falling back between v4 and v6
+    /// reaches the same machine over the same internet, where falling back from a private address to a
+    /// public one would put an address on the open internet into a bookmark that was asked to stay off it.
+    /// So the row loses its tick and cannot get it back while that choice stands.
+    /// </remarks>
+    [Fact]
+    public async Task ChoosingThePrivateNetwork_LeavesAServerWithoutOneUnimportable()
+    {
+        await UnlockedAsync();
+
+        var wizard = Wizard(Project(WebServer, """
+            {
+              "id": 3,
+              "name": "db-01",
+              "status": "running",
+              "public_net": { "ipv4": { "ip": "203.0.113.20" } },
+              "private_net": [ { "ip": "10.0.0.4" } ]
+            }
+            """));
+
+        wizard.Token = HetznerToken;
+
+        await wizard.ScanCommand.ExecuteAsync(null);
+
+        wizard.SelectedCount.ShouldBe(2);
+
+        wizard.UseAddressCommand.Execute(HetznerAddressKind.Private);
+
+        var public_ = wizard.Rows.Single(row => string.Equals(row.Name, "web-01", StringComparison.Ordinal));
+        var inside = wizard.Rows.Single(row => string.Equals(row.Name, "db-01", StringComparison.Ordinal));
+
+        public_.CanImport.ShouldBeFalse("it is on no private network");
+        public_.IsSelected.ShouldBeFalse();
+        public_.Address.ShouldBe("—");
+
+        inside.CanImport.ShouldBeTrue();
+        inside.Address.ShouldBe("10.0.0.4");
+
+        wizard.SelectedCount.ShouldBe(1);
+
+        // Neither direction of "tick everything" can reach it, which is what "not importable" has to mean.
+        wizard.ToggleAllCommand.Execute(null);
+
+        public_.IsSelected.ShouldBeFalse();
+        inside.IsSelected.ShouldBeFalse("that press was the untick, since everything reachable was ticked");
+
+        wizard.ToggleAllCommand.Execute(null);
+
+        public_.IsSelected.ShouldBeFalse();
+        inside.IsSelected.ShouldBeTrue();
+
+        await wizard.ImportCommand.ExecuteAsync(null);
+
+        shell.Vault!.Hosts.ShouldHaveSingleItem().Host.Hostname.ShouldBe("10.0.0.4");
+    }
+
+    /// <remarks>
+    /// Changing the address choice must not throw away ticks somebody set — but changing the login user has
+    /// to re-ask "is this already here", because the user is half of what that is decided on.
+    /// </remarks>
+    [Fact]
+    public async Task ChangingTheLoginUser_ReasksWhetherTheKeychainAlreadyHasIt()
+    {
+        await UnlockedAsync();
+        var vault = shell.Vault!;
+
+        await AddHostAsync(vault, "prod-db");
+
+        var wizard = Wizard(Project("""
+            {
+              "id": 1,
+              "name": "db",
+              "status": "running",
+              "public_net": { "ipv4": { "ip": "db.internal" } }
+            }
+            """));
+
+        wizard.Token = HetznerToken;
+        wizard.Username = "deploy";
+
+        await wizard.ScanCommand.ExecuteAsync(null);
+
+        wizard.Rows.ShouldHaveSingleItem().AlreadyPresent.ShouldBeTrue();
+
+        wizard.Username = "ubuntu";
+
+        wizard.Rows[0].AlreadyPresent.ShouldBeFalse("a different account on that machine is a different host");
+    }
+
+    /// <summary>
+    /// A server with no public IPv4 still imports, and the row says what was assumed to reach it.
+    /// </summary>
+    /// <remarks>
+    /// IPv6-only is a whole Hetzner price tier rather than an edge case. The address is the first in the
+    /// routed /64 — the API reports a network, which nothing can dial — and that is a convention of
+    /// Hetzner's own images rather than a fact, so it is on the row and in the stored note.
+    /// </remarks>
+    [Fact]
+    public async Task AnIPv6OnlyServer_ImportsWithWhatWasAssumedWrittenDown()
+    {
+        await UnlockedAsync();
+
+        var wizard = Wizard(Project("""
+            {
+              "id": 5,
+              "name": "v6-only",
+              "status": "running",
+              "public_net": { "ipv4": null, "ipv6": { "ip": "2a01:4f8:1c17:d00::/64" } }
+            }
+            """));
+
+        wizard.Token = HetznerToken;
+
+        await wizard.ScanCommand.ExecuteAsync(null);
+
+        var row = wizard.Rows.ShouldHaveSingleItem();
+
+        row.Address.ShouldBe("2a01:4f8:1c17:d00::1");
+        row.HasWarning.ShouldBeTrue();
+        row.Meaning.ShouldContain("No public IPv4");
+
+        await wizard.ImportCommand.ExecuteAsync(null);
+
+        var host = shell.Vault!.Hosts.ShouldHaveSingleItem();
+
+        host.Host.Hostname.ShouldBe("2a01:4f8:1c17:d00::1");
+        host.Host.Notes.ShouldNotBeNull().ShouldContain("No public IPv4");
+    }
+
+    /// <remarks>
+    /// After an import the list is asked again rather than cleared, so a row that was just stored says
+    /// "already here" — which is what makes coming back and importing the rest of the project harmless and
+    /// visible rather than harmless and confusing.
+    /// </remarks>
+    [Fact]
+    public async Task AfterImporting_TheListSaysWhichOnesAreNowHere()
+    {
+        await UnlockedAsync();
+
+        var wizard = Wizard(Project(WebServer));
+
+        wizard.Token = HetznerToken;
+
+        await wizard.ScanCommand.ExecuteAsync(null);
+        await wizard.ImportCommand.ExecuteAsync(null);
+
+        wizard.ReviewCommand.Execute(null);
+
+        wizard.Step.ShouldBe(HetznerImportStep.Choose);
+
+        var row = wizard.Rows.ShouldHaveSingleItem();
+
+        row.AlreadyPresent.ShouldBeTrue();
+        row.IsSelected.ShouldBeFalse("importing it twice takes a click");
+    }
+
+    // ---- Where it lives in the shell ----
+
+    /// <remarks>
+    /// The wizard is drawn over the Preferences page inside settings mode, exactly as the ssh_config
+    /// importer is: the nav stays lit on Preferences and the titlebar offers "Back to preferences". What
+    /// would silently come apart is the content column — two importers and one page beneath them.
+    /// </remarks>
+    [Fact]
+    public async Task TheHetznerWizardOpensOverPreferencesAndBacksOutToIt()
+    {
+        await UnlockedAsync();
+
+        shell.ShowScreenCommand.Execute(ShellScreen.HetznerImport);
+
+        shell.IsHetznerImportOpen.ShouldBeTrue();
+        shell.IsImporterOpen.ShouldBeTrue("the titlebar's back button asks this one");
+        shell.IsSettingsPreferencesPage.ShouldBeTrue("the nav stays lit on Preferences");
+        shell.IsSettingsPreferencesContentShowing.ShouldBeFalse("the wizard is what the column draws");
+
+        shell.CloseImportCommand.Execute(null);
+
+        shell.IsHetznerImportOpen.ShouldBeFalse();
+        shell.IsSettingsMode.ShouldBeTrue("back to preferences, not out of settings");
+        shell.IsSettingsPreferencesContentShowing.ShouldBeTrue();
+    }
+
+    /// <remarks>
+    /// Opening one closes the other. They share a content column, and two importers drawn over each other
+    /// would leave whichever was on top looking like the one the back button belongs to.
+    /// </remarks>
+    [Fact]
+    public async Task OpeningOneImporterClosesTheOther()
+    {
+        await UnlockedAsync();
+
+        shell.ShowScreenCommand.Execute(ShellScreen.Import);
+        shell.IsImportOpen.ShouldBeTrue();
+
+        shell.ShowScreenCommand.Execute(ShellScreen.HetznerImport);
+
+        shell.IsImportOpen.ShouldBeFalse();
+        shell.IsHetznerImportOpen.ShouldBeTrue();
+
+        shell.ShowScreenCommand.Execute(ShellScreen.Import);
+
+        shell.IsHetznerImportOpen.ShouldBeFalse();
+        shell.IsImportOpen.ShouldBeTrue();
+    }
+
+    /// <summary>
+    /// Reopening the wizard puts it back on step one.
+    /// </summary>
+    /// <remarks>
+    /// A decision rather than an omission. The first step holds a credential this deliberately does not
+    /// keep, so a "resumed" second step would be a list nothing on screen has the means to refresh — and it
+    /// would go on looking current for as long as somebody left the application open.
+    /// </remarks>
+    [Fact]
+    public async Task ReopeningTheWizard_StartsAtTheTokenAgain()
+    {
+        await UnlockedAsync();
+
+        var wizard = shell.HetznerImportScreen.ShouldNotBeNull();
+
+        // Driven through the shell's own view model rather than the one this file builds, because what is
+        // being checked is what OpenHetznerImport does to the screen the shell is holding.
+        wizard.Token = HetznerToken;
+        wizard.Step = HetznerImportStep.Choose;
+
+        shell.ShowScreenCommand.Execute(ShellScreen.HetznerImport);
+
+        wizard.Step.ShouldBe(HetznerImportStep.Token);
+        wizard.Rows.ShouldBeEmpty();
+    }
+
+    // ---- Helpers ----
+
+    /// <summary>A server carrying enough to be imported, used wherever the shape is not what is being tested.</summary>
+    private const string WebServer = """
+        {
+          "id": 2,
+          "name": "web-01",
+          "status": "running",
+          "public_net": { "ipv4": { "ip": "203.0.113.10" } }
+        }
+        """;
+
+    /// <summary>The wizard, over a Hetzner that answers with exactly this.</summary>
+    private HetznerImportViewModel Wizard(StubHetznerResponse response) =>
+        new(shell.Vault!, new HetznerCloudClient(new HttpClient(new StubHetzner(response))));
+
+    /// <summary>One page holding these servers and saying there are no more.</summary>
+    private static StubHetznerResponse Project(params string[] servers) =>
+        new(
+            HttpStatusCode.OK,
+            $$"""
+            {
+              "servers": [ {{string.Join(",", servers)}} ],
+              "meta": { "pagination": { "page": 1, "per_page": 50, "next_page": null } }
+            }
+            """);
+
+    private sealed record StubHetznerResponse(HttpStatusCode Status, string Body);
+
+    /// <summary>Answers every request the same way. What varies between these tests is the body, not the sequence.</summary>
+    private sealed class StubHetzner(StubHetznerResponse response) : HttpMessageHandler
+    {
+        protected override Task<HttpResponseMessage> SendAsync(
+            HttpRequestMessage request,
+            CancellationToken cancellationToken) =>
+            Task.FromResult(new HttpResponseMessage(response.Status)
+            {
+                Content = new StringContent(response.Body, Encoding.UTF8, "application/json"),
+            });
+    }
+}