RFC: API to check if domain is valid (for on-demand HTTPS in Caddy)

[scotthansonde]

Caddy is a web server that can do automatic HTTPS, automatically provisioning TLS certificates (from Let's Encrypt) for a domain and keeping them renewed. This already works with PagePark if the domains are manually configured in Caddy. However, Caddy can also request certificates on demand for domains not specified in the configuration. This would be handy for PagePark so HTTPS would automatically work when domains are added.

For security reasons Caddy should only provision domains that are valid for the server, otherwise the server is open to attack. Caddy checks for valid domains by "asking" an HTTP endpoint if it has permission to obtain a certificate for a certain domain. Once it has a certificate it will never "ask" again and renew the certificate silently.

I am proposing a localhost endpoint '/check' in PagePark that would answer this request. It takes a 'domain' query parameter. It returns 200 if the domain is configured in PagePark and 400 if not. This initial version handles both regular domains and wildcard domains in PagePark. It does not handle the "default" directory. Additional configuration would be needed to handle "default" domains.

The endpoint would be inserted into the case statement currently at line 1050 of pagepark.js:

case "/check":
	if (!parsedUrl.query.domain) {
		httpRespond (500, "text/plain", "Nothing to check");
	} else {
		getDomainFolder(parsedUrl.query.domain, function (folder, host) {
			if (host === pageparkPrefs.defaultDomanFolderName) { 
				httpRespond (400, 'text/plain', 'Do not serve');
			} else {
				httpRespond (200, 'text/plain', host);
			}
		}); 
	}
	break;

Here is a sample "Caddyfile" (Caddy configuration file) that will answer all HTTPS requests ("asking" PagePark if it needs to obtain a certificate) and redirects all HTTP requests to HTTPS (the default):

{
	on_demand_tls {
		ask http://localhost:1339/check
		interval 2m
		burst    5
		}
	}
https:// {
	tls {
		on_demand
		}
	reverse_proxy localhost:1339
	}

Caddy provides packages for Ubuntu and can easily be installed on Digital Ocean.

[scripting]

@papascott -- thanks for this RFC.

I understand what's going on, I think -- first a question -- Does the name of the call have to be /check?

It's kind of a generic name from the PP point of view. Check what?

Also I think i'm going to look for a way to make sure the request is coming from the local host.

Dave

[scotthansonde]

@scripting The call can be called anything you want, no need to use '/check'. And checking for localhost sounds like a very good idea!

[scripting]

OK, I have it working.

http://localhost:1340/isdomainvalid?domain=local.karass.co

Returns local.karass.co because it is one of the domains my local copy of PagePark serves.

The new version of PP is released. Here's the new call. Please review, and let me know if it looks right.

There's a change note for this work.

[scotthansonde]

I updated my test PagePark server and Caddy configuration to the new call, everything seems to work! 👍