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.Import.Tests/DodoSSH.Client.Import.Tests.csproj

@@ -1,9 +1,15 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <!--
-    The ssh_config reader, against strings. No disk, because the parser takes its include reader as a
+    Both readers, each against a stand-in for the world it reads.
+
+    The ssh_config one runs against strings. No disk, because the parser takes its include reader as a
     parameter — which is what lets Include, the one directive whose behaviour is a file-system behaviour,
     be covered by ordinary unit tests.
+
+    The Hetzner one runs against a stubbed HttpMessageHandler, which is the same trade: no account, no token
+    and no network, and every question about what the client decides from what Hetzner said still answerable.
+    What that leaves for a person is in docs/manual-checks.md, 2.11a onwards.
   -->
 
   <ItemGroup>

tests/DodoSSH.Client.Import.Tests/HetznerCloudClientTests.cs

@@ -0,0 +1,416 @@
+using System.Net;
+using System.Text;
+using DodoSSH.Client.Import;
+
+namespace DodoSSH.Client.Import.Tests;
+
+/// <summary>
+/// Reading a Hetzner Cloud project, against a stubbed transport.
+/// </summary>
+/// <remarks>
+/// <para>
+/// No socket, for the reason <c>LinuxUpdateChannelTests</c> gives: every question here is what this client
+/// decides from what Hetzner said, and a real request would add an account, a token and a network to the
+/// assertions without adding anything to what is being checked.
+/// </para>
+/// <para>
+/// The bodies are real shapes rather than minimal ones. An importer's whole value is agreeing with the
+/// source about what it means — the IPv6 field holding a network rather than an address, and a server that
+/// has no IPv4 at all, are both ordinary in a Hetzner project and both are exactly where an importer that
+/// was nearly right would produce bookmarks that nearly connect.
+/// </para>
+/// </remarks>
+public sealed class HetznerCloudClientTests
+{
+    private const string Token = "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789";
+
+    private static CancellationToken Cancellation => TestContext.Current.CancellationToken;
+
+    [Fact]
+    public async Task APageOfServers_ArrivesWithWhatTheProjectSaidAboutThem()
+    {
+        var import = await ReadAsync(OnePage(OneServer));
+
+        var server = import.Servers.ShouldHaveSingleItem();
+
+        server.Id.ShouldBe(42);
+        server.Name.ShouldBe("web-01");
+        server.Status.ShouldBe("running");
+        server.PublicIPv4.ShouldBe("203.0.113.10");
+        server.ServerType.ShouldBe("cx22");
+        server.Location.ShouldBe("fsn1 · Falkenstein, DE");
+        server.Image.ShouldBe("ubuntu-24.04");
+        server.Labels.ShouldBe(["env=prod", "role=web"]);
+        import.Warnings.ShouldBeEmpty();
+    }
+
+    /// <remarks>
+    /// The token goes in an <c>Authorization: Bearer</c> header and nowhere else — never a query parameter,
+    /// which is the shape that ends up in somebody's proxy log.
+    /// </remarks>
+    [Fact]
+    public async Task TheTokenTravelsAsABearerHeader()
+    {
+        var stub = new StubHetzner([OnePage(OneServer)]);
+
+        await new HetznerCloudClient(new HttpClient(stub)).ListServersAsync(Token, Cancellation);
+
+        var request = stub.Requests.ShouldHaveSingleItem();
+
+        request.Authorization.ShouldBe($"Bearer {Token}");
+        request.Uri.ShouldNotContain(Token);
+        request.Uri.ShouldContain("per_page=50");
+    }
+
+    /// <summary>
+    /// Every page is followed, which is what keeps a short list from looking like a complete one.
+    /// </summary>
+    /// <remarks>
+    /// Fifty-one servers in a project is enough to meet this, and an importer that showed the first fifty
+    /// would present a list nobody has any reason to doubt.
+    /// </remarks>
+    [Fact]
+    public async Task EveryPageIsFollowed()
+    {
+        var stub = new StubHetzner([
+            Page(nextPage: 2, """{ "id": 1, "name": "web-01" }"""),
+            Page(nextPage: 3, """{ "id": 2, "name": "web-02" }"""),
+            Page(nextPage: null, """{ "id": 3, "name": "web-03" }"""),
+        ]);
+
+        var import = await new HetznerCloudClient(new HttpClient(stub))
+            .ListServersAsync(Token, Cancellation);
+
+        import.Servers.Select(server => server.Name).ShouldBe(["web-01", "web-02", "web-03"]);
+        stub.Requests.Select(request => request.Uri).ShouldAllBe(uri => uri.Contains("page="));
+        stub.Requests.Count.ShouldBe(3);
+    }
+
+    /// <remarks>
+    /// A refused token is the failure this wizard meets most, because the value is shown once in the Hetzner
+    /// console and a half-copied one fails exactly like a wrong one. So the message says where tokens come
+    /// from, and <c>IsTokenProblem</c> is what sends the wizard back to the step that has the box.
+    /// </remarks>
+    [Fact]
+    public async Task ARefusedToken_SaysWhereTokensComeFromAndIsMarkedAsTheTokensFault()
+    {
+        var stub = new StubHetzner([
+            new StubResponse(
+                HttpStatusCode.Unauthorized,
+                """{ "error": { "code": "unauthorized", "message": "unable to authenticate" } }"""),
+        ]);
+
+        var failure = await Should.ThrowAsync<HetznerCloudException>(
+            () => new HetznerCloudClient(new HttpClient(stub)).ListServersAsync(Token, Cancellation));
+
+        failure.IsTokenProblem.ShouldBeTrue();
+        failure.Code.ShouldBe("unauthorized");
+        failure.Message.ShouldContain("API tokens");
+        failure.Message.ShouldContain("unable to authenticate", Case.Insensitive);
+    }
+
+    /// <remarks>
+    /// The other half of that split: Hetzner having a bad minute is not a reason to send somebody back to
+    /// re-type a token that was fine.
+    /// </remarks>
+    [Fact]
+    public async Task AFaultAtHetznersEnd_IsNotTheTokensFault()
+    {
+        var stub = new StubHetzner([new StubResponse(HttpStatusCode.BadGateway, "<html>nope</html>")]);
+
+        var failure = await Should.ThrowAsync<HetznerCloudException>(
+            () => new HetznerCloudClient(new HttpClient(stub)).ListServersAsync(Token, Cancellation));
+
+        failure.IsTokenProblem.ShouldBeFalse();
+        failure.Message.ShouldContain("502");
+    }
+
+    /// <remarks>
+    /// Refused before anything is sent, because a header value carrying a line break throws from inside
+    /// <c>HttpClient</c> — a stack trace where the honest answer is a sentence.
+    /// </remarks>
+    [Fact]
+    public async Task ATokenWithALineBreakInTheMiddle_IsRefusedWithoutAskingHetzner()
+    {
+        var stub = new StubHetzner([OnePage(OneServer)]);
+
+        var failure = await Should.ThrowAsync<HetznerCloudException>(
+            () => new HetznerCloudClient(new HttpClient(stub))
+                .ListServersAsync("abcdef\n0123456789", Cancellation));
+
+        failure.Message.ShouldContain("64 letters and digits");
+        stub.Requests.ShouldBeEmpty();
+    }
+
+    /// <remarks>Pasting out of the console brings a trailing newline often enough to be worth handling.</remarks>
+    [Fact]
+    public async Task ATokenPastedWithSurroundingWhitespace_IsTrimmedRatherThanRefused()
+    {
+        var stub = new StubHetzner([OnePage(OneServer)]);
+
+        await new HetznerCloudClient(new HttpClient(stub)).ListServersAsync($"  {Token}\n", Cancellation);
+
+        stub.Requests.ShouldHaveSingleItem().Authorization.ShouldBe($"Bearer {Token}");
+    }
+
+    /// <summary>
+    /// A server with no IPv4 at all, which is a whole Hetzner price tier rather than an edge case.
+    /// </summary>
+    /// <remarks>
+    /// Two things are being checked and the second is the one that matters. The address is the first in the
+    /// routed /64, because what the API reports is a network and nothing can dial a network. And it carries
+    /// a warning, because that address is a convention of Hetzner's own images rather than a fact the API
+    /// stated — an import that silently guessed would produce a bookmark that fails to connect with no
+    /// indication of why.
+    /// </remarks>
+    [Fact]
+    public async Task AServerWithNoIPv4_DialsTheFirstAddressOfItsSixtyFourAndSaysSo()
+    {
+        var import = await ReadAsync(OnePage("""
+            {
+              "id": 7,
+              "name": "v6-only",
+              "status": "running",
+              "public_net": {
+                "ipv4": null,
+                "ipv6": { "ip": "2a01:4f8:1c17:d00::/64" }
+              }
+            }
+            """));
+
+        var server = import.Servers.ShouldHaveSingleItem();
+
+        server.HasPublicIPv4.ShouldBeFalse();
+        server.FirstIPv6Address.ShouldBe("2a01:4f8:1c17:d00::1");
+
+        var address = server.Resolve(HetznerAddressKind.PublicIPv4).ShouldNotBeNull();
+
+        address.Value.ShouldBe("2a01:4f8:1c17:d00::1");
+        address.Warning.ShouldNotBeNull().ShouldContain("No public IPv4");
+    }
+
+    /// <remarks>
+    /// The v6 choice warns even where it is the one that was asked for, on the same reasoning: the address
+    /// is inferred from a network either way.
+    /// </remarks>
+    [Fact]
+    public async Task ChoosingIPv6_StillSaysTheAddressWasInferredFromANetwork()
+    {
+        var import = await ReadAsync(OnePage(OneServer));
+
+        var address = import.Servers[0].Resolve(HetznerAddressKind.PublicIPv6).ShouldNotBeNull();
+
+        address.Value.ShouldBe("2a01:4f8:1c17:d00::1");
+        address.Warning.ShouldNotBeNull().ShouldContain("2a01:4f8:1c17:d00::/64");
+    }
+
+    /// <summary>
+    /// The private choice does not fall back, and that asymmetry is the point.
+    /// </summary>
+    /// <remarks>
+    /// Falling back between v4 and v6 reaches the same machine over the same internet. 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 a server with no private network is simply not importable under that choice.
+    /// </remarks>
+    [Fact]
+    public async Task AServerOnNoPrivateNetwork_HasNoPrivateAddressToOffer()
+    {
+        var import = await ReadAsync(OnePage(OneServer));
+
+        import.Servers[0].Resolve(HetznerAddressKind.Private).ShouldBeNull();
+    }
+
+    [Fact]
+    public async Task AServerOnAPrivateNetwork_DialsItWithoutAWarning()
+    {
+        var import = await ReadAsync(OnePage("""
+            {
+              "id": 9,
+              "name": "db-01",
+              "private_net": [ { "ip": "10.0.0.4" } ]
+            }
+            """));
+
+        var address = import.Servers[0].Resolve(HetznerAddressKind.Private).ShouldNotBeNull();
+
+        address.Value.ShouldBe("10.0.0.4");
+        address.Warning.ShouldBeNull();
+    }
+
+    /// <remarks>
+    /// Two private networks is a real shape and the first one is a choice this makes rather than a fact, so
+    /// it is said out loud — the same rule the IPv6 address follows.
+    /// </remarks>
+    [Fact]
+    public async Task AServerOnTwoPrivateNetworks_TakesTheFirstAndSaysThereWereTwo()
+    {
+        var import = await ReadAsync(OnePage("""
+            {
+              "id": 9,
+              "name": "db-01",
+              "private_net": [ { "ip": "10.0.0.4" }, { "ip": "10.1.0.4" } ]
+            }
+            """));
+
+        var address = import.Servers[0].Resolve(HetznerAddressKind.Private).ShouldNotBeNull();
+
+        address.Value.ShouldBe("10.0.0.4");
+        address.Warning.ShouldNotBeNull().ShouldContain("2 private networks");
+    }
+
+    /// <summary>What is stored, and what is deliberately not.</summary>
+    /// <remarks>
+    /// The note keeps what does not go stale — the id, the plan, where it runs, what it was built from. The
+    /// power state is not in it: a note saying "running" about a machine somebody switched off last March is
+    /// worse than no note, so status is a column on the import screen and never a stored fact.
+    /// </remarks>
+    [Fact]
+    public async Task WhatIsStored_CarriesTheProjectsContextAndNotItsPowerState()
+    {
+        var import = await ReadAsync(OnePage(OneServer));
+        var server = import.Servers[0];
+
+        var host = server.ToSecret(
+            server.Resolve(HetznerAddressKind.PublicIPv4).ShouldNotBeNull(),
+            "root",
+            22);
+
+        host.Label.ShouldBe("web-01");
+        host.Hostname.ShouldBe("203.0.113.10");
+        host.Username.ShouldBe("root");
+        host.Port.ShouldBe(22);
+        host.SshKeyId.ShouldBeNull("the private half of a key was never Hetzner's to hand over");
+
+        var notes = host.Notes.ShouldNotBeNull();
+
+        notes.ShouldContain("server 42");
+        notes.ShouldContain("cx22");
+        notes.ShouldContain("fsn1 · Falkenstein, DE");
+        notes.ShouldContain("ubuntu-24.04");
+        notes.ShouldContain("env=prod");
+        notes.ShouldNotContain("running");
+
+        host.TryValidate(out _).ShouldBeTrue();
+    }
+
+    /// <remarks>
+    /// A blank login user stores none rather than storing an empty one, which is what the ssh_config import
+    /// does for an entry that named no <c>User</c>.
+    /// </remarks>
+    [Fact]
+    public async Task ABlankLoginUser_StoresNoUsername()
+    {
+        var import = await ReadAsync(OnePage(OneServer));
+        var server = import.Servers[0];
+
+        server.ToSecret(server.Resolve(HetznerAddressKind.PublicIPv4)!, "   ", 22).Username.ShouldBeNull();
+    }
+
+    /// <remarks>
+    /// A server with no name would arrive as a bookmark called nothing, which <c>HostSecret.TryValidate</c>
+    /// refuses outright — so it is named for its id and the project-level warning says one was.
+    /// </remarks>
+    [Fact]
+    public async Task AServerWithNoName_IsOfferedUnderItsIdAndWarnedAbout()
+    {
+        var import = await ReadAsync(OnePage("""{ "id": 512, "status": "off" }"""));
+
+        import.Servers.ShouldHaveSingleItem().Name.ShouldBe("server-512");
+        import.Warnings.ShouldHaveSingleItem().ShouldContain("server-512");
+    }
+
+    /// <remarks>
+    /// Everything but the id is optional in practice — a server built from a snapshot has no image, and one
+    /// mid-creation has no datacentre yet. None of that is a reason to refuse the whole page.
+    /// </remarks>
+    [Fact]
+    public async Task AServerTheApiDescribedSparsely_StillImports()
+    {
+        var import = await ReadAsync(OnePage("""{ "id": 3, "name": "fresh", "status": "initializing" }"""));
+
+        var server = import.Servers.ShouldHaveSingleItem();
+
+        server.ServerType.ShouldBeNull();
+        server.Location.ShouldBeNull();
+        server.Image.ShouldBeNull();
+        server.Labels.ShouldBeEmpty();
+        server.Resolve(HetznerAddressKind.PublicIPv4).ShouldBeNull("it has no address of any kind yet");
+    }
+
+    // ---- Helpers ----
+
+    /// <summary>A server carrying everything the API can say about one, used wherever the shape is not the point.</summary>
+    private const string OneServer = """
+        {
+          "id": 42,
+          "name": "web-01",
+          "status": "running",
+          "public_net": {
+            "ipv4": { "id": 1, "ip": "203.0.113.10", "blocked": false },
+            "ipv6": { "id": 2, "ip": "2a01:4f8:1c17:d00::/64", "blocked": false }
+          },
+          "private_net": [],
+          "server_type": { "id": 22, "name": "cx22", "cores": 2 },
+          "datacenter": {
+            "id": 4,
+            "name": "fsn1-dc14",
+            "location": { "name": "fsn1", "city": "Falkenstein", "country": "DE" }
+          },
+          "image": { "id": 100, "name": "ubuntu-24.04", "os_flavor": "ubuntu" },
+          "labels": { "role": "web", "env": "prod" }
+        }
+        """;
+
+    private static Task<HetznerImport> ReadAsync(StubResponse page) =>
+        new HetznerCloudClient(new HttpClient(new StubHetzner([page]))).ListServersAsync(Token, Cancellation);
+
+    private static StubResponse OnePage(string server) => Page(nextPage: null, server);
+
+    private static StubResponse Page(int? nextPage, string server) =>
+        new(
+            HttpStatusCode.OK,
+            $$"""
+            {
+              "servers": [ {{server}} ],
+              "meta": { "pagination": { "page": 1, "per_page": 50, "next_page": {{Next(nextPage)}} } }
+            }
+            """);
+
+    private static string Next(int? page) =>
+        page is { } value ? value.ToString(System.Globalization.CultureInfo.InvariantCulture) : "null";
+
+    private sealed record StubResponse(HttpStatusCode Status, string Body);
+
+    private sealed record SeenRequest(string Uri, string? Authorization);
+
+    /// <summary>
+    /// Answers each request with the next scripted response, and remembers what was asked.
+    /// </summary>
+    /// <remarks>
+    /// Scripted in order rather than keyed by URL, because the thing being checked in the paging test is the
+    /// sequence: a client that asked for page one three times would pass a lookup by address and produce the
+    /// same list three times over.
+    /// </remarks>
+    private sealed class StubHetzner(IReadOnlyList<StubResponse> responses) : HttpMessageHandler
+    {
+        private int served;
+
+        internal List<SeenRequest> Requests { get; } = [];
+
+        protected override Task<HttpResponseMessage> SendAsync(
+            HttpRequestMessage request,
+            CancellationToken cancellationToken)
+        {
+            Requests.Add(new SeenRequest(
+                request.RequestUri!.AbsoluteUri,
+                request.Headers.Authorization?.ToString()));
+
+            var scripted = responses[Math.Min(served++, responses.Count - 1)];
+
+            return Task.FromResult(new HttpResponseMessage(scripted.Status)
+            {
+                Content = new StringContent(scripted.Body, Encoding.UTF8, "application/json"),
+            });
+        }
+    }
+}