implement the On-Demand TLS feature

README.md

@@ -134,6 +134,34 @@ root path. Services deployed to other paths on the same host will use the same
 TLS settings as those specified for the root path.
 
 
+### On-demand TLS
+
+In addition to the automatic TLS functionality, Kamal Proxy can also dynamically obtain a TLS certificate 
+for any host allowed by an external API endpoint of your choice. This avoids hard-coding hosts in the configuration, especially when you don't know the hosts at startup.
+
+    kamal-proxy deploy service1 --target web-1:3000 --host "" --tls --tls-on-demand-url="http://localhost:4567/check"
+
+The On-demand URL endpoint must return a 200 HTTP status code to allow certificate issuance. 
+Kamal Proxy will call the on-demand URL with a query string parameter `host` containing the hostname received by Kamal Proxy (for example, `?host=hostname.example.com`).
+
+- The HTTP request to the on-demand URL will time out after 2 seconds. If the endpoint is unreachable or slow, certificate issuance will fail for that host.
+- If the endpoint returns any status other than 200, Kamal Proxy will log the status code and up to 256 bytes of the response body for debugging.
+- **Security note:** The on-demand URL acts as an authorization gate for certificate issuance. It should be protected and only allow trusted hosts. If compromised, unauthorized certificates could be issued.
+- If `--tls-on-demand-url` is not set, Kamal Proxy falls back to a static whitelist of hosts.
+- If using a local path (for example, `/allow-host`), ensure that endpoint is reachable through your deployed app and returns quickly.
+
+**Best practice:**
+- Ensure your on-demand endpoint is fast, reliable, and protected (e.g., behind authentication or on a private network).
+- Only allow hosts you control to prevent abuse.
+
+Example endpoint logic (pseudo-code):
+
+    if host in allowed_hosts:
+        return 200 OK
+    else:
+        return 403 Forbidden
+
+
 ### Custom TLS certificate
 
 When you obtained your TLS certificate manually, manage your own certificate authority,
@@ -143,6 +171,29 @@ your certificate file and the corresponding private key:
     kamal-proxy deploy service1 --target web-1:3000 --host app1.example.com --tls --tls-certificate-path cert.pem --tls-private-key-path key.pem
 
 
+## TLSOnDemandUrl Option
+
+The `TLSOnDemandUrl` option can be set to either:
+
+- **An external URL** (e.g., `https://my-allow-service/allow-host`):
+  - The service will make an HTTP request to this external URL to determine if a certificate should be issued for a given host.
+
+- **A local path** (e.g., `/allow-host`):
+  - The service will internally route a request to this path using its own load balancer and handler. You must ensure your service responds to this path appropriately.
+
+### Example: External URL
+```yaml
+TLSOnDemandUrl: "https://my-allow-service/allow-host"
+```
+
+### Example: Local Path
+```yaml
+TLSOnDemandUrl: "/allow-host"
+```
+
+When using a local path, your service should implement a handler for the specified path (e.g., `/allow-host`) that returns `200 OK` to allow certificate issuance, or another status code to deny it.
+
+
 ## Specifying `run` options with environment variables
 
 In some environments, like when running a Docker container, it can be convenient

internal/cmd/deploy.go

@@ -34,6 +34,7 @@ func newDeployCommand() *deployCommand {
 	deployCommand.cmd.Flags().BoolVar(&deployCommand.args.ServiceOptions.StripPrefix, "strip-path-prefix", true, "With --path-prefix, strip prefix from request before forwarding")
 
 	deployCommand.cmd.Flags().BoolVar(&deployCommand.args.ServiceOptions.TLSEnabled, "tls", false, "Configure TLS for this target (requires a non-empty host)")
+	deployCommand.cmd.Flags().StringVar(&deployCommand.args.ServiceOptions.TLSOnDemandUrl, "tls-on-demand-url", "", "Will make an HTTP request to the given URL, asking whether a host is allowed to have a certificate issued.")
 	deployCommand.cmd.Flags().BoolVar(&deployCommand.tlsStaging, "tls-staging", false, "Use Let's Encrypt staging environment for certificate provisioning")
 	deployCommand.cmd.Flags().StringVar(&deployCommand.args.ServiceOptions.TLSCertificatePath, "tls-certificate-path", "", "Configure custom TLS certificate path (PEM format)")
 	deployCommand.cmd.Flags().StringVar(&deployCommand.args.ServiceOptions.TLSPrivateKeyPath, "tls-private-key-path", "", "Configure custom TLS private key path (PEM format)")
@@ -101,6 +102,11 @@ func (c *deployCommand) preRun(cmd *cobra.Command, args []string) error {
 	}
 
 	if c.args.ServiceOptions.TLSEnabled {
+		if c.args.ServiceOptions.TLSOnDemandUrl != "" {
+			c.args.ServiceOptions.Hosts = []string{""}
+			return nil
+		}
+
 		if len(c.args.ServiceOptions.Hosts) == 0 {
 			return fmt.Errorf("host must be set when using TLS")
 		}

internal/cmd/deploy_test.go

@@ -76,3 +76,40 @@ func TestDeployCommand_CanonicalHostValidation(t *testing.T) {
 		})
 	}
 }
+
+func TestDeployCommand_preRun_TLSOnDemandUrl(t *testing.T) {
+	t.Run("TLS enabled with TLS on-demand URL should set hosts to empty string", func(t *testing.T) {
+		deployCmd := newDeployCommand()
+
+		// Set flags for TLS with on-demand URL
+		deployCmd.cmd.Flags().Set("target", "http://localhost:8080")
+		deployCmd.cmd.Flags().Set("tls", "true")
+		deployCmd.cmd.Flags().Set("tls-on-demand-url", "http://example.com/validate")
+		deployCmd.cmd.Flags().Set("host", "example.com")
+		deployCmd.cmd.Flags().Set("path-prefix", "/")
+
+		// Call preRun
+		err := deployCmd.preRun(deployCmd.cmd, []string{"test-service"})
+		require.NoError(t, err)
+
+		// Verify that hosts is set to empty string
+		assert.Equal(t, []string{""}, deployCmd.args.ServiceOptions.Hosts)
+	})
+
+	t.Run("TLS enabled without TLS on-demand URL should not modify hosts", func(t *testing.T) {
+		deployCmd := newDeployCommand()
+
+		// Set flags for TLS without on-demand URL
+		deployCmd.cmd.Flags().Set("target", "http://localhost:8080")
+		deployCmd.cmd.Flags().Set("tls", "true")
+		deployCmd.cmd.Flags().Set("host", "example.com")
+		deployCmd.cmd.Flags().Set("path-prefix", "/")
+
+		// Call preRun
+		err := deployCmd.preRun(deployCmd.cmd, []string{"test-service"})
+		require.NoError(t, err)
+
+		// Verify that hosts is not modified
+		assert.Equal(t, []string{"example.com"}, deployCmd.args.ServiceOptions.Hosts)
+	})
+}

internal/server/router_test.go

@@ -1,8 +1,10 @@
 package server
 
 import (
+	"context"
+	"crypto/tls"
 	"encoding/json"
-    "crypto/tls"
+	"fmt"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -11,6 +13,8 @@ import (
 	"testing"
 	"time"
 
+	"golang.org/x/crypto/acme/autocert"
+
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -211,45 +215,45 @@ func TestRouter_UpdatingOptions(t *testing.T) {
 }
 
 func TestRouter_CanonicalHostRedirect(t *testing.T) {
-    router := testRouter(t)
-    _, target := testBackend(t, "first", http.StatusOK)
+	router := testRouter(t)
+	_, target := testBackend(t, "first", http.StatusOK)
 
-    serviceOptions := defaultServiceOptions
-    serviceOptions.Hosts = []string{"example.com", "www.example.com"}
-    serviceOptions.CanonicalHost = "example.com"
+	serviceOptions := defaultServiceOptions
+	serviceOptions.Hosts = []string{"example.com", "www.example.com"}
+	serviceOptions.CanonicalHost = "example.com"
 
-    require.NoError(t, router.DeployService("service1", []string{target}, defaultEmptyReaders, serviceOptions, defaultTargetOptions, defaultDeploymentOptions))
+	require.NoError(t, router.DeployService("service1", []string{target}, defaultEmptyReaders, serviceOptions, defaultTargetOptions, defaultDeploymentOptions))
 
-    statusCode, _ := sendGETRequest(router, "http://www.example.com/")
-    assert.Equal(t, http.StatusMovedPermanently, statusCode)
+	statusCode, _ := sendGETRequest(router, "http://www.example.com/")
+	assert.Equal(t, http.StatusMovedPermanently, statusCode)
 
-    statusCode, body := sendGETRequest(router, "http://example.com/")
-    assert.Equal(t, http.StatusOK, statusCode)
-    assert.Equal(t, "first", body)
+	statusCode, body := sendGETRequest(router, "http://example.com/")
+	assert.Equal(t, http.StatusOK, statusCode)
+	assert.Equal(t, "first", body)
 }
 
 func TestRouter_CanonicalHostRedirectWithTLS(t *testing.T) {
-    router := testRouter(t)
-    _, target := testBackend(t, "first", http.StatusOK)
+	router := testRouter(t)
+	_, target := testBackend(t, "first", http.StatusOK)
 
-    serviceOptions := defaultServiceOptions
-    serviceOptions.Hosts = []string{"example.com", "www.example.com"}
-    serviceOptions.CanonicalHost = "example.com"
-    serviceOptions.TLSEnabled = true
-    serviceOptions.TLSRedirect = true
+	serviceOptions := defaultServiceOptions
+	serviceOptions.Hosts = []string{"example.com", "www.example.com"}
+	serviceOptions.CanonicalHost = "example.com"
+	serviceOptions.TLSEnabled = true
+	serviceOptions.TLSRedirect = true
 
-    require.NoError(t, router.DeployService("service1", []string{target}, defaultEmptyReaders, serviceOptions, defaultTargetOptions, defaultDeploymentOptions))
+	require.NoError(t, router.DeployService("service1", []string{target}, defaultEmptyReaders, serviceOptions, defaultTargetOptions, defaultDeploymentOptions))
 
-    // Should go directly to https://example.com in a single redirect
-    statusCode, _ := sendGETRequest(router, "http://www.example.com/")
-    assert.Equal(t, http.StatusMovedPermanently, statusCode)
+	// Should go directly to https://example.com in a single redirect
+	statusCode, _ := sendGETRequest(router, "http://www.example.com/")
+	assert.Equal(t, http.StatusMovedPermanently, statusCode)
 
-    // HTTPS request to non-canonical host should redirect to canonical host but remain HTTPS
-    req := httptest.NewRequest(http.MethodGet, "https://www.example.com/", nil)
-    req.TLS = &tls.ConnectionState{}
-    w := httptest.NewRecorder()
-    router.ServeHTTP(w, req)
-    assert.Equal(t, http.StatusMovedPermanently, w.Result().StatusCode)
+	// HTTPS request to non-canonical host should redirect to canonical host but remain HTTPS
+	req := httptest.NewRequest(http.MethodGet, "https://www.example.com/", nil)
+	req.TLS = &tls.ConnectionState{}
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	assert.Equal(t, http.StatusMovedPermanently, w.Result().StatusCode)
 }
 
 func TestRouter_DeploymentsWithErrorsDoNotUpdateService(t *testing.T) {
@@ -771,6 +775,129 @@ func TestRouter_RestoreLastSavedState(t *testing.T) {
 	assert.Equal(t, "third", body)
 }
 
+func TestRouter_RestoreLastSavedState_WithTLSOnDemandURL_HostPolicyUsesOnDemandChecker(t *testing.T) {
+	statePath := filepath.Join(t.TempDir(), "state.json")
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	state := fmt.Sprintf(`[{
+	  "name":"ondemand",
+	  "options":{
+	    "hosts":[""],
+	    "path_prefixes":["/"],
+	    "tls_enabled":true,
+	    "tls_certificate_path":"",
+	    "tls_private_key_path":"",
+	    "tls_on_demand_url":"%s",
+	    "tls_redirect":false,
+	    "canonical_host":"",
+	    "acme_directory":"",
+	    "acme_cache_path":"",
+	    "error_page_path":"",
+	    "strip_prefix":true,
+	    "writer_affinity_timeout":1000000000,
+	    "read_targets_accept_websockets":false
+	  },
+	  "target_options":{
+	    "health_check_config":{"path":"/up","port":0,"interval":1000000000,"timeout":5000000000,"host":""},
+	    "response_timeout":30000000000,
+	    "buffer_requests":false,
+	    "buffer_responses":false,
+	    "max_memory_buffer_size":1048576,
+	    "max_request_body_size":0,
+	    "max_response_body_size":0,
+	    "log_request_headers":null,
+	    "log_response_headers":null,
+	    "forward_headers":false,
+	    "scope_cookie_paths":false
+	  },
+	  "active_targets":["localhost:3000"],
+	  "active_readers":[],
+	  "rollout_targets":null,
+	  "rollout_readers":null,
+	  "pause_controller":{"state":0,"stop_message":"","fail_after":0},
+	  "rollout_controller":null
+	}]`, server.URL)
+	require.NoError(t, os.WriteFile(statePath, []byte(state), 0600))
+
+	router := NewRouter(statePath)
+	require.NoError(t, router.RestoreLastSavedState())
+
+	service := router.services.Get("ondemand")
+	require.NotNil(t, service)
+	manager, ok := service.certManager.(*autocert.Manager)
+	require.True(t, ok)
+	require.NotNil(t, manager.HostPolicy)
+
+	assert.NoError(t, manager.HostPolicy(context.Background(), "tenant.example.com"))
+}
+
+func TestRouter_RestoreLastSavedState_WithTLSOnDemandURL_HostPolicyDeniesWhenCheckerRejects(t *testing.T) {
+	statePath := filepath.Join(t.TempDir(), "state-deny.json")
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Query().Get("host") == "tenant.example.com" {
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		w.WriteHeader(http.StatusForbidden)
+	}))
+	defer server.Close()
+
+	state := fmt.Sprintf(`[{
+	  "name":"ondemand-deny",
+	  "options":{
+	    "hosts":[""],
+	    "path_prefixes":["/"],
+	    "tls_enabled":true,
+	    "tls_certificate_path":"",
+	    "tls_private_key_path":"",
+	    "tls_on_demand_url":"%s",
+	    "tls_redirect":false,
+	    "canonical_host":"",
+	    "acme_directory":"",
+	    "acme_cache_path":"",
+	    "error_page_path":"",
+	    "strip_prefix":true,
+	    "writer_affinity_timeout":1000000000,
+	    "read_targets_accept_websockets":false
+	  },
+	  "target_options":{
+	    "health_check_config":{"path":"/up","port":0,"interval":1000000000,"timeout":5000000000,"host":""},
+	    "response_timeout":30000000000,
+	    "buffer_requests":false,
+	    "buffer_responses":false,
+	    "max_memory_buffer_size":1048576,
+	    "max_request_body_size":0,
+	    "max_response_body_size":0,
+	    "log_request_headers":null,
+	    "log_response_headers":null,
+	    "forward_headers":false,
+	    "scope_cookie_paths":false
+	  },
+	  "active_targets":["localhost:3000"],
+	  "active_readers":[],
+	  "rollout_targets":null,
+	  "rollout_readers":null,
+	  "pause_controller":{"state":0,"stop_message":"","fail_after":0},
+	  "rollout_controller":null
+	}]`, server.URL)
+	require.NoError(t, os.WriteFile(statePath, []byte(state), 0600))
+
+	router := NewRouter(statePath)
+	require.NoError(t, router.RestoreLastSavedState())
+
+	service := router.services.Get("ondemand-deny")
+	require.NotNil(t, service)
+	manager, ok := service.certManager.(*autocert.Manager)
+	require.True(t, ok)
+	require.NotNil(t, manager.HostPolicy)
+
+	assert.NoError(t, manager.HostPolicy(context.Background(), "tenant.example.com"))
+	assert.Error(t, manager.HostPolicy(context.Background(), "denied.example.com"))
+}
+
 // Helpers
 
 func testRouter(t *testing.T) *Router {