Merge pull request #18 from tayloraswift/https-everywhere

HTTPS everywhere

Author: tayloraswift

.gitignore

@@ -5,6 +5,7 @@
 .vscode
 
 Assets/secrets/
+TestCertificates/*.pem
 TestDeployment/data/
 
 node_modules/

Assets/css/Main.css

@@ -0,0 +1,41 @@
+# Generating TLS certificates
+
+To simplify the implementation and facilitate testing, Unidoc uses TLS (HTTPS) everywhere, even when running locally.
+
+For a seamless development experience, we recommend using [mkcert](https://github.com/FiloSottile/mkcert) to generate a local certificate authority (CA) for your development environment.
+
+## Installing mkcert
+
+The easiest way to install `mkcert` is to download one of its prebuilt binaries.
+
+```bash
+$ curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
+chmod +x mkcert-v*-linux-amd64
+```
+
+## Generating a local certificate authority
+
+```bash
+$ ./mkcert-v1.4.4-linux-amd64 -install
+``````
+
+## Generating a local certificate
+
+If the `mkcert-v1.4.4-linux-amd64` binary is located in your home directory, you can generate a certificate for `localhost` by running the following from the repository root:
+
+```bash
+$ cd TestCertificates
+$ ~/mkcert-v1.4.4-linux-amd64 localhost
+
+```
+
+Then, rename the generated files to `fullchain.pem` and `privkey.pem`.
+
+```bash
+$ mv localhost.pem fullchain.pem
+$ mv localhost-key.pem privkey.pem
+```
+
+You should now be able to run the Unidoc server locally and access it without browser warnings.
+
+Keep in mind that the certificate is only valid for `localhost`; hostnames like `0.0.0.0` will still raise browser warnings.

Guides/GeneratingCertificates.md

@@ -74,12 +74,12 @@ let package:Package = .init(
         .package(url: "https://github.com/tayloraswift/swift-hash", .upToNextMinor(
             from: "0.5.0")),
         .package(url: "https://github.com/tayloraswift/swift-mongodb", .upToNextMinor(
-            from: "0.8.2")),
+            from: "0.8.3")),
 
         .package(url: "https://github.com/apple/swift-atomics", .upToNextMinor(
             from: "1.1.0")),
         .package(url: "https://github.com/apple/swift-nio", .upToNextMinor(
-            from: "2.57.0")),
+            from: "2.58.0")),
         .package(url: "https://github.com/apple/swift-nio-http2", .upToNextMinor(
             from: "1.27.0")),
         .package(url: "https://github.com/apple/swift-nio-ssl", .upToNextMinor(
@@ -177,6 +177,7 @@ let package:Package = .init(
                 .target(name: "HTML"),
                 .target(name: "HTTP"),
                 .product(name: "NIOHTTP1", package: "swift-nio"),
+                .product(name: "NIOHTTP2", package: "swift-nio-http2"),
                 .product(name: "NIOSSL", package: "swift-nio-ssl"),
                 .product(name: "TraceableErrors", package: "swift-grammar"),
             ]),

Package.resolved

@@ -1,6 +1,6 @@
 <div align="center">
 
-<strong><em><code>unidoc</code></em></strong><br><small><code>0.2.3</code></small>
+<strong><em><code>unidoc</code></em></strong><br><small><code>0.2.4</code></small>
 
 [![ci build status](https://github.com/kelvin13/swift-unidoc/actions/workflows/build.yml/badge.svg)](https://github.com/kelvin13/swift-unidoc/actions/workflows/build.yml)
 
@@ -104,6 +104,8 @@ Unidoc is tightly-integrated with Swiftinit, but you can run it locally to previ
 
 Unidoc uses [MongoDB](https://www.mongodb.com/) to persist documentation. This allows for fast startup times as Unidoc performs almost no initialization, but requires you to have an active MongoDB replica set running on your local machine. See [`Testing.md`](Guides/Testing.md) for instructions on setting up a local environment.
 
+Unidoc uses HTTPS everywhere. See [`GeneratingCertificates.md`](Guides/GeneratingCertificates.md) for how to generate a local and certificate and certificate authority for `localhost`.
+
 TODO: Add example for running the Unidoc server locally.
 
 TODO: Add example for invoking the Unidoc compiler.

Package.swift

@@ -1,13 +1,19 @@
+import NIOSSL
+
 @frozen public
 struct Localhost:ServerAuthority
 {
-    @inlinable internal
-    init()
+    public
+    let tls:NIOSSLContext
+
+    @inlinable public
+    init(tls:NIOSSLContext)
     {
+        self.tls = tls
     }
 
     @inlinable public static
-    var scheme:ServerScheme { .http }
+    var scheme:ServerScheme { .https }
     @inlinable public static
     var domain:String { "127.0.0.1" }
 }

README.md

@@ -2,34 +2,24 @@ import HTML
 import NIOCore
 import NIOHTTP1
 import NIOPosix
+import NIOSSL
 import TraceableErrors
 
 public
-protocol ServerAuthority<SecurityContext>:Sendable
+protocol ServerAuthority:Sendable
 {
-    associatedtype SecurityContext = Never
-
     static
     var scheme:ServerScheme { get }
     static
     var domain:String { get }
 
-    var tls:SecurityContext? { get }
+    var tls:NIOSSLContext { get }
 
     static
     func redact(error:any Error) -> String
 }
-
-extension ServerAuthority where Self == Localhost
-{
-    @inlinable public static
-    var localhost:Self { .init() }
-}
-
-extension ServerAuthority<Never>
+extension ServerAuthority
 {
-    @inlinable public
-    var tls:SecurityContext? { nil }
     /// Dumps detailed information about the caught error. This information will be shown to
     /// *anyone* accessing the server. In production, we strongly recommend overriding this
     /// default implementation to avoid inadvertently exposing sensitive data via type
@@ -66,8 +56,6 @@ extension ServerAuthority
     {
         switch self.scheme
         {
-        case .http(port: 80):           return "http://\(self.domain)\(uri)"
-        case .http(port: let port):     return "http://\(self.domain):\(port)\(uri)"
         case .https(port: 443):         return "https://\(self.domain)\(uri)"
         case .https(port: let port):    return "https://\(self.domain):\(port)\(uri)"
         }

Sources/HTTPServer/Authorities/Localhost.swift

@@ -2,15 +2,11 @@
 enum ServerScheme
 {
     case https(port:Int = 443)
-    case http(port:Int = 80)
 }
 extension ServerScheme
 {
     @inlinable public static
     var https:Self { .https() }
-
-    @inlinable public static
-    var http:Self { .http() }
 }
 extension ServerScheme
 {
@@ -19,7 +15,6 @@ extension ServerScheme
     {
         switch self
         {
-        case .http(port: let port):     return port
         case .https(port: let port):    return port
         }
     }
@@ -28,7 +23,6 @@ extension ServerScheme
     {
         switch self
         {
-        case .http:             return "http"
         case .https:            return "https"
         }
     }

Sources/HTTPServer/Authorities/ServerAuthority.swift

@@ -1,7 +1,7 @@
 import HTTP
 import NIOCore
 import NIOPosix
-import NIOHTTP1
+import NIOHTTP2
 import NIOSSL
 
 public
@@ -30,26 +30,14 @@ extension HTTPServerDelegate
         {
             (channel:any Channel) -> EventLoopFuture<Void> in
 
-            let endpoint:ServerInterfaceHandler<Authority, Self> = .init(
-                address: channel.remoteAddress,
-                server: self)
-
-            guard let tls:NIOSSLContext = authority.tls as? NIOSSLContext
-            else
-            {
-                return channel.pipeline.configureHTTPServerPipeline(withErrorHandling: true)
-                    .flatMap
-                {
-                    channel.pipeline.addHandler(endpoint)
-                }
-            }
-            return  channel.pipeline.addHandler(NIOSSLServerHandler.init(context: tls))
-                    .flatMap
+            channel.pipeline.addHandler(NIOSSLServerHandler.init(context: authority.tls))
+                .flatMap
             {
-                    channel.pipeline.configureHTTPServerPipeline(withErrorHandling: true)
-                    .flatMap
+                channel.configureCommonHTTPServerPipeline
                 {
-                    channel.pipeline.addHandler(endpoint)
+                    $0.pipeline.addHandler(ServerInterfaceHandler<Authority, Self>.init(
+                        address: channel.remoteAddress,
+                        server: self))
                 }
             }
         }