Updates

Author: aritchie

readme.md

@@ -23,7 +23,7 @@ JWT, OpenAPI, HPACK, QPACK — is built on what is in the box.
 | [Shiny.Net.HttpServer.DocumentDb](https://www.nuget.org/packages/Shiny.Net.HttpServer.DocumentDb) | Publishes a Shiny.DocumentDb type as a REST resource — list, by-id, count, CRUD, merge-patch and a live SSE tail |
 | [Shiny.Net.HttpServer.WebDav](https://www.nuget.org/packages/Shiny.Net.HttpServer.WebDav) | A WebDAV (RFC 4918) class 1 & 2 server over a directory — mount an app's storage in Finder, Windows Explorer or any WebDAV client |
 | [Shiny.Net.HttpServer.Grpc](https://www.nuget.org/packages/Shiny.Net.HttpServer.Grpc) | gRPC and gRPC-Web — unary, streaming and bidirectional methods over the same HTTP/2 stack, with serialization you supply |
-| [Shiny.Net.HttpServer.CommandLine](https://www.nuget.org/packages/Shiny.Net.HttpServer.CommandLine) | A .NET tool — `shinyhttpserver` — that serves a directory over HTTP with the file browser, with basic auth, per-operation permissions, and a QR code of the LAN address in the banner so a phone can scan its way in |
+| [Shiny.Net.HttpServer.CommandLine](https://www.nuget.org/packages/Shiny.Net.HttpServer.CommandLine) | A .NET tool — `shinyhttpserver` — that serves a directory over HTTP with the file browser, with basic auth, per-operation permissions, and a QR code in the banner so a phone can scan its way in — `--tunnel` swaps the LAN address for a public pinggy.io tunnel so the phone need not be on the same network |
 
 ## Getting Started
 

skills/shiny-httpserver/SKILL.md

@@ -99,6 +99,9 @@ triggers:
 - serve a directory from the command line
 - QR code in the terminal
 - open a served directory on a phone
+- share a folder over the internet
+- --tunnel
+- --tunnel-token
 - Shiny.Net.HttpServer.WebDav
 - MapWebDav
 - WebDavOptions
@@ -210,6 +213,14 @@ address plus the URL in full, so "get this folder onto my phone" is the tool ans
 `-a localhost` keeps it to the machine, `--no-qr` drops the code. Basic auth (`-u`) over plain HTTP
 refuses to start on a non-loopback address, which the default now is: pair it with `--https`.
 
+`--tunnel` is the answer to "share this folder with someone not on my network": it opens a
+`QuickTunnel` to pinggy.io and the QR code carries the public HTTPS address instead of the LAN one.
+Because the tunnel feeds `HttpServer.ServeAsync` directly, `--tunnel -a localhost` binds nothing on
+the LAN and is reachable only through the tunnel — and a tunnelled connection counts as encrypted
+transport, so `-u` works over it without `--https` or `--allow-insecure-auth`. Anonymous tunnels stop
+after 60 minutes; `--tunnel-token <token>` lifts that and implies `--tunnel`. Always say that the
+address is public when you suggest it.
+
 ## The four tiers — the spine of this library
 
 Every new API belongs to one of these. Say which when you introduce one. They compose in one app.

src/Shiny.Net.HttpServer.CommandLine/Cli.cs

@@ -83,6 +83,17 @@ public static RootCommand Build(Func<ServeSettings, CancellationToken, Task<int>
             Description = "Serves over HTTPS with a self-signed certificate generated at startup. Clients will warn about it."
         };
 
+        var tunnelOpt = new Option<bool>("--tunnel")
+        {
+            Description = "Opens a public pinggy.io tunnel and shares that address instead of the LAN one. Anonymous tunnels stop after 60 minutes."
+        };
+
+        var tunnelTokenOpt = new Option<string?>("--tunnel-token")
+        {
+            Description = "A pinggy.io access token, which lifts the 60 minute cap an anonymous tunnel has. Implies --tunnel.",
+            HelpName = "token"
+        };
+
         var hiddenOpt = new Option<bool>("--hidden")
         {
             Description = "Includes dotfiles and hidden files in listings and downloads."
@@ -118,6 +129,8 @@ public static RootCommand Build(Func<ServeSettings, CancellationToken, Task<int>
             authChangesOpt,
             insecureAuthOpt,
             httpsOpt,
+            tunnelOpt,
+            tunnelTokenOpt,
             hiddenOpt,
             maxUploadOpt,
             noQrOpt,
@@ -138,6 +151,8 @@ public static RootCommand Build(Func<ServeSettings, CancellationToken, Task<int>
                 AuthChangesOnly = parseResult.GetValue(authChangesOpt),
                 AllowInsecureAuth = parseResult.GetValue(insecureAuthOpt),
                 UseHttps = parseResult.GetValue(httpsOpt),
+                UseTunnel = parseResult.GetValue(tunnelOpt) || parseResult.GetValue(tunnelTokenOpt) is { Length: > 0 },
+                TunnelToken = parseResult.GetValue(tunnelTokenOpt),
                 ServeHidden = parseResult.GetValue(hiddenOpt),
                 MaxUploadBytes = parseResult.GetRequiredValue(maxUploadOpt),
                 ShowQr = !parseResult.GetValue(noQrOpt),

src/Shiny.Net.HttpServer.CommandLine/Runner.cs

@@ -1,3 +1,4 @@
+using System.ComponentModel;
 using System.Net;
 using System.Net.NetworkInformation;
 using System.Net.Sockets;
@@ -6,6 +7,7 @@
 using Microsoft.Extensions.Logging;
 using Shiny.Net.HttpServer.FileBrowser;
 using Shiny.Net.HttpServer.Security;
+using Shiny.Net.HttpServer.Ssh;
 
 namespace Shiny.Net.HttpServer.CommandLine;
 
@@ -29,6 +31,11 @@ public static async Task<int> RunAsync(ServeSettings settings, CancellationToken
                 o.TimestampFormat = "HH:mm:ss ";
             })
             .SetMinimumLevel(settings.Verbose ? LogLevel.Debug : LogLevel.Warning)
+
+            // The tunnel warns that it is trusting an unverified host key, which is exactly what a
+            // quick tunnel does by design - and the banner says so in plainer words a few lines
+            // later. Left in for --verbose, kept out of a normal run's first three lines.
+            .AddFilter("Shiny.Net.HttpServer.Ssh", settings.Verbose ? LogLevel.Debug : LogLevel.Error)
         );
 
         builder.Configure(o =>
@@ -103,7 +110,26 @@ public static async Task<int> RunAsync(ServeSettings settings, CancellationToken
             });
         }
 
-        PrintBanner(settings, prefix);
+        // The tunnel hands connections straight to ServeAsync, so it is up before - and independent
+        // of - the listener. That is what makes "--tunnel -a localhost" a real combination: nothing
+        // on the LAN, everything through the tunnel.
+        await using var tunnel = settings.UseTunnel
+            ? QuickTunnel.For(
+                server,
+                QuickTunnelHost.Pinggy,
+                settings.TunnelToken,
+                loggerFactory: server.Services?.GetService<ILoggerFactory>()
+            )
+            : null;
+
+        var tunnelUrl = tunnel is null ? null : await OpenTunnelAsync(tunnel, cancellationToken).ConfigureAwait(false);
+
+        PrintBanner(settings, prefix, tunnelUrl);
+
+        // The address changes on every reconnect, which kills whatever is already on screen - so a
+        // new one is announced, with its own code, rather than leaving a dead link as the last word.
+        if (tunnel is not null)
+            tunnel.PropertyChanged += (_, e) => OnTunnelUrlChanged(settings, prefix, tunnel, e);
 
         try
         {
@@ -124,6 +150,61 @@ public static async Task<int> RunAsync(ServeSettings settings, CancellationToken
     }
 
 
+    /// <summary>
+    /// Brings the tunnel up, or explains why there is none. A tunnel that will not open is not a
+    /// reason to refuse to serve: the directory is still on this network, and the banner still has
+    /// somewhere to point.
+    /// </summary>
+    static async Task<string?> OpenTunnelAsync(QuickTunnel tunnel, CancellationToken cancellationToken)
+    {
+        Console.WriteLine();
+        Console.WriteLine("  opening tunnel...");
+
+        try
+        {
+            var url = await tunnel.StartAsync(cancellationToken).ConfigureAwait(false);
+            if (url is { Length: > 0 })
+                return url;
+
+            Error(tunnel.LastError ?? "The tunnel connected but never reported an address.");
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            Error($"The tunnel could not be opened - {ex.Message}");
+        }
+
+        Warn("Serving on this network only.");
+        return null;
+    }
+
+
+    static void OnTunnelUrlChanged(ServeSettings settings, string prefix, QuickTunnel tunnel, PropertyChangedEventArgs e)
+    {
+        if (e.PropertyName != nameof(QuickTunnel.PublicUrl) || tunnel.PublicUrl is not { Length: > 0 } url)
+            return;
+
+        Console.WriteLine();
+        Warn("The tunnel reconnected on a new address. The previous one no longer answers.");
+        Line("Tunnel", TunnelUrl(url, prefix));
+
+        if (settings.ShowQr)
+        {
+            Console.WriteLine();
+            PrintQr(TunnelUrl(url, prefix));
+        }
+        Console.WriteLine();
+    }
+
+
+    /// <summary>The tunnel terminates at the site root, so the mount point has to be put back on.</summary>
+    internal static string TunnelUrl(string url, string prefix)
+        => prefix == "/" ? url.TrimEnd('/') + "/" : url.TrimEnd('/') + prefix;
+
+
     static bool NeedsWriteGuard(Permissions permissions)
     {
         var create = permissions.Has(Permissions.Create);
@@ -159,6 +240,7 @@ Basic auth over plain HTTP on {settings.Address} would send the password across
 
                  Pick one:
                    --https                  serve over TLS with a self-signed certificate
+                   --tunnel -a localhost    reach it only through the tunnel, which is encrypted
                    --address localhost      keep the server on this machine
                    --allow-insecure-auth    send it anyway
                  """
@@ -180,7 +262,7 @@ static async ValueTask LogRequestAsync(HttpContext context, RequestDelegate next
     }
 
 
-    static void PrintBanner(ServeSettings settings, string prefix)
+    static void PrintBanner(ServeSettings settings, string prefix, string? tunnelUrl)
     {
         Console.WriteLine();
         Console.WriteLine("shinyhttpserver");
@@ -190,6 +272,9 @@ static void PrintBanner(ServeSettings settings, string prefix)
         foreach (var url in Urls(settings, prefix))
             Line("URL", url);
 
+        if (tunnelUrl is not null)
+            Line("Tunnel", TunnelUrl(tunnelUrl, prefix));
+
         Line("Operations", settings.Permissions.Describe());
         Line(
             "Auth",
@@ -203,14 +288,32 @@ static void PrintBanner(ServeSettings settings, string prefix)
 
         Console.WriteLine();
 
+        // Said before the write warning, because it is what turns that warning from "the office
+        // network" into "the internet".
+        if (tunnelUrl is not null)
+        {
+            Warn(
+                "The tunnel is public: anyone holding the address can reach this directory, and the traffic passes through pinggy.io."
+                + (settings.TunnelToken is { Length: > 0 } ? "" : " An anonymous tunnel stops after 60 minutes.")
+            );
+        }
+
         if (settings.Permissions.AllowsChanges() && !settings.AuthEnabled)
-            Warn("Writes are open to anyone who can reach this server. Add --user name:password.");
+        {
+            Warn(
+                tunnelUrl is null
+                    ? "Writes are open to anyone who can reach this server. Add --user name:password."
+                    : "Writes are open to anyone on the internet holding the tunnel address. Add --user name:password."
+            );
+        }
 
         if (settings.UseHttps)
             Warn("The certificate is self-signed and generated at startup, so clients will not trust it.");
 
+        // The tunnel address is the one worth scanning when there is one: it reaches a phone that
+        // is not on this network at all, which the LAN address does not.
         if (settings.ShowQr)
-            PrintQr(settings, prefix);
+            PrintQr(tunnelUrl is null ? ShareableUrl(settings, prefix) : TunnelUrl(tunnelUrl, prefix));
 
         Console.WriteLine("Ctrl+C to stop");
         Console.WriteLine();
@@ -219,11 +322,10 @@ static void PrintBanner(ServeSettings settings, string prefix)
 
     /// <summary>
     /// The point of the code is a phone that is not this machine, so it carries the address another
-    /// device can reach - and nothing at all when the server is only listening to itself.
+    /// device can reach - and nothing at all when there is no such address.
     /// </summary>
-    static void PrintQr(ServeSettings settings, string prefix)
+    static void PrintQr(string? url)
     {
-        var url = ShareableUrl(settings, prefix);
         if (url == null || !QrCode.TryEncode(url, out var code))
             return;
 

src/Shiny.Net.HttpServer.CommandLine/ServeSettings.cs

@@ -26,6 +26,12 @@ public sealed record ServeSettings
 
     public required bool UseHttps { get; init; }
 
+    /// <summary>Opens a pinggy.io quick tunnel, so the directory is reachable from off this network.</summary>
+    public required bool UseTunnel { get; init; }
+
+    /// <summary>A pinggy.io access token, which lifts the 60 minute cap an anonymous tunnel has.</summary>
+    public string? TunnelToken { get; init; }
+
     /// <summary>Prints a scannable QR code of the address another device can reach.</summary>
     public bool ShowQr { get; init; } = true;
 

src/Shiny.Net.HttpServer.CommandLine/Shiny.Net.HttpServer.CommandLine.csproj

@@ -22,6 +22,7 @@
 
   <ItemGroup>
     <ProjectReference Include="../Shiny.Net.HttpServer/Shiny.Net.HttpServer.csproj" />
+    <ProjectReference Include="../Shiny.Net.HttpServer.Ssh/Shiny.Net.HttpServer.Ssh.csproj" />
   </ItemGroup>
 
   <ItemGroup>

tests/Shiny.Net.HttpServer.Tests/CommandLineTests.cs

@@ -105,6 +105,45 @@ public async Task Normalizes_a_prefix()
         Assert.Equal("/", (await ParseAsync("--prefix", "/")).UrlPrefix);
     }
 
+    /// <summary>
+    /// The tunnel is what puts the directory on the public internet, so nothing but asking for it
+    /// turns it on.
+    /// </summary>
+    [Fact]
+    public async Task Leaves_the_tunnel_closed_unless_asked()
+    {
+        var settings = await ParseAsync();
+
+        Assert.False(settings.UseTunnel);
+        Assert.Null(settings.TunnelToken);
+    }
+
+    [Fact]
+    public async Task Opens_a_tunnel_when_asked()
+        => Assert.True((await ParseAsync("--tunnel")).UseTunnel);
+
+    /// <summary>A token is only ever used to open a tunnel, so supplying one is asking for one.</summary>
+    [Fact]
+    public async Task Reads_a_tunnel_token_and_takes_it_as_asking_for_a_tunnel()
+    {
+        var settings = await ParseAsync("--tunnel-token", "abc123");
+
+        Assert.True(settings.UseTunnel);
+        Assert.Equal("abc123", settings.TunnelToken);
+    }
+
+    /// <summary>
+    /// The tunnel terminates at the site root, so a prefixed mount has to be put back on - the
+    /// address in the banner and in the QR code is the one that has to open the listing.
+    /// </summary>
+    [Theory]
+    [InlineData("https://x.free.pinggy.net", "/", "https://x.free.pinggy.net/")]
+    [InlineData("https://x.free.pinggy.net/", "/", "https://x.free.pinggy.net/")]
+    [InlineData("https://x.free.pinggy.net", "/files", "https://x.free.pinggy.net/files")]
+    [InlineData("https://x.free.pinggy.net/", "/files", "https://x.free.pinggy.net/files")]
+    public void Puts_the_prefix_back_on_the_tunnel_address(string url, string prefix, string expected)
+        => Assert.Equal(expected, Runner.TunnelUrl(url, prefix));
+
     [Theory]
     [InlineData(new[] { "--allow", "frobnicate" }, "is not an operation")]
     [InlineData(new[] { "--user", "nopassword" }, "is not a credential")]

tests/Shiny.Net.HttpServer.Tests/QrCodeTests.cs

@@ -159,6 +159,21 @@ public void Fits_an_ordinary_terminal()
         => Assert.True(QrConsole.Width(Code()) <= 40);
 
 
+    /// <summary>
+    /// A tunnel address is far longer than a LAN one - pinggy builds the hostname out of the
+    /// client's address, so an IPv6 machine gets the worst case. It still has to encode, and still
+    /// has to fit a terminal, or "--tunnel" prints no code at all.
+    /// </summary>
+    [Fact]
+    public void Fits_a_tunnel_address_too()
+    {
+        const string Url = "https://gyjjf-2605-8d80-5c0-d61d-616e-e6d7-7250-2508.free.pinggy.net/";
+
+        Assert.True(QrCode.TryEncode(Url, out var code));
+        Assert.True(QrConsole.Width(code) <= 80);
+    }
+
+
     [Fact]
     public void Draws_with_nothing_but_block_glyphs()
         => Assert.All(QrConsole.Render(Code()), line => Assert.All(line.ToCharArray(), c => Assert.Contains(c, " █▀▄")));