feat: enhance subdomain assignment and add cert-manager configuration for wildcard TLS

Author: Timothy Dodd

CLAUDE.md

@@ -19,11 +19,15 @@ from the .NET version).
   role, analogous to ngrok's cloud). Runs three listeners:
   - a WebSocket server (default `:8001`) that tunnel clients dial into. Clients
     **authenticate with a bearer API token** on the handshake; the host maps the
-    token to a user and **assigns a subdomain dynamically** — the client's
-    requested name (`Ntunl-Subdomain` header / `desiredSubdomain` config) if it's
-    free, otherwise a random `word+number` — then pushes back the public URL.
-    Subdomains are first-come-first-served per live connection; nothing is
-    pre-reserved.
+    token to a user and **assigns a subdomain** (`assignSubdomain` in tunnel.go),
+    then pushes back the public URL. Two modes, set by `clientDomain.subDomains`:
+    - **Pool** (list non-empty): assign a free name from that fixed list (honoring
+      a requested one if it's a free pool member), reject when exhausted. Route a
+      handful of subdomains to the host — no wildcard DNS needed.
+    - **Fully dynamic** (empty list): requested name if free, else a random
+      `word+number` (needs wildcard DNS to be routable).
+    Either way it's first-come-first-served per live connection; nothing is
+    pre-reserved per user.
   - a public HTTP server (default `:9200`) that receives outside traffic, maps the
     request's subdomain (`apple.domain.com` → client `apple`) to a connected
     client, forwards the request over the socket, relays the response, and counts

deploy/k3s/README.md

@@ -29,8 +29,13 @@ storage provisioner (for the SQLite volume) and **Traefik** (ingress).
    and `ingress.yaml` (the three hosts).
 3. **Set the admin password** in `secret.yaml` (or delete the Secret to fall back
    to `admin`/`admin`). It only applies on first run with an empty database.
-4. **DNS**: point `*.<domain>`, `tunnel.<domain>`, and `portal.<domain>` at your
-   k3s ingress IP.
+4. **DNS**: one **DNS-only** wildcard A record covers everything (it also matches
+   `portal.`/`tunnel.`):
+   ```
+   *.<domain>   A   <traefik external IP>   # kubectl -n kube-system get svc traefik -o wide
+   ```
+   A records can't specify a port, so clients reach 443/80 and Traefik routes by
+   hostname to ports 8002/8001/9200.
 
 ## Apply
 
@@ -58,10 +63,10 @@ kubectl -n ntunl logs deploy/ntunl-host
 ## TLS / HTTPS
 
 Public URLs are `https://<sub>.<domain>` and clients use `wss://`, so you need a
-**wildcard certificate** at the ingress. The simplest path is cert-manager with a
-DNS-01 issuer producing `*.<domain>`; put it in `ntunl-wildcard-tls` and uncomment
-the `tls:` block in `ingress.yaml`. Until then, traffic is plain HTTP and clients
-must use `sslEnabled: false` against `tunnel.<domain>:80`.
+**wildcard certificate** at the ingress (the `tls:` block in `ingress.yaml` already
+references `ntunl-wildcard-tls`). Issue it with cert-manager + Cloudflare DNS-01 —
+see [`cert-manager/`](./cert-manager). Until the cert is issued, traffic is plain
+HTTP and clients must use `sslEnabled: false` against `<domain>:80`.
 
 ## Notes
 

deploy/k3s/cert-manager/README.md

@@ -0,0 +1,70 @@
+# Wildcard TLS for the NTunl host (direct-to-IP, no Cloudflare proxy)
+
+When you route `*.<domain>` straight at the k3s ingress IP with a **DNS-only**
+wildcard A record (instead of through a Cloudflare proxied tunnel), Cloudflare's
+edge certificate no longer applies — you must terminate TLS yourself. These
+manifests issue a Let's Encrypt **wildcard** cert via cert-manager + Cloudflare
+DNS-01 and hand it to the Ingress.
+
+These are intentionally **not** part of the top-level `kustomization.yaml`: they
+depend on cert-manager's CRDs, which must be installed first.
+
+## Steps
+
+1. **Install cert-manager** (one-time, cluster-wide):
+   ```bash
+   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
+   ```
+
+2. **DNS** — point a wildcard at your ingress IP, **DNS-only / grey cloud**
+   (proxied wildcards are Enterprise-only and won't work here):
+   ```
+   *.example.com   A   <traefik external IP>
+   ```
+   Find the IP: `kubectl -n kube-system get svc traefik -o wide`.
+
+3. **Cloudflare API token** — create one (Zone:DNS:Edit + Zone:Zone:Read on your
+   zone), put it in `cloudflare-api-token-secret.yaml`, and apply it into the
+   `cert-manager` namespace.
+
+4. **Edit the domain/email** in `clusterissuer.yaml` and `certificate.yaml`
+   (replace `example.com` and the email). Tip: use the Let's Encrypt **staging**
+   server first to avoid rate limits, then switch to prod.
+
+5. **Apply**:
+   ```bash
+   kubectl apply -f deploy/k3s/cert-manager/cloudflare-api-token-secret.yaml
+   kubectl apply -f deploy/k3s/cert-manager/clusterissuer.yaml
+   kubectl apply -f deploy/k3s/cert-manager/certificate.yaml
+   ```
+
+6. **Verify** the cert was issued into the `ntunl-wildcard-tls` secret that the
+   Ingress references:
+   ```bash
+   kubectl -n ntunl get certificate ntunl-wildcard
+   kubectl -n ntunl describe certificate ntunl-wildcard   # watch for "Issued"
+   ```
+
+The Ingress (`../ingress.yaml`) already references `secretName: ntunl-wildcard-tls`,
+so once the cert is `Ready`, `https://<sub>.example.com` and `wss://tunnel...`
+serve a valid certificate.
+
+## Client config for this path
+
+Because TLS is now terminated at Traefik on 443:
+
+```jsonc
+{
+  "sslEnabled": true,
+  "allowInvalidCertificates": false,   // real Let's Encrypt cert
+  "ntunlAddress": "tunnel.example.com:443"
+}
+```
+
+## Trade-off vs. Cloudflare Tunnel
+
+Direct-to-IP exposes your node's public IP and you manage TLS yourself, but it's
+the only way to get wildcard/dynamic subdomains without a Cloudflare Enterprise
+plan. The portal and tunnel-handshake hostnames could still go through a
+Cloudflare proxied tunnel if you prefer to hide those two — but the wildcard
+proxy must be direct.

deploy/k3s/cert-manager/certificate.yaml

@@ -0,0 +1,17 @@
+# Wildcard certificate for the NTunl host. cert-manager writes the issued cert
+# into the ntunl-wildcard-tls secret, which the Ingress references.
+# The wildcard covers every client subdomain AND portal./tunnel. hostnames.
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: ntunl-wildcard
+  namespace: ntunl
+spec:
+  secretName: ntunl-wildcard-tls
+  issuerRef:
+    name: letsencrypt-cloudflare
+    kind: ClusterIssuer
+  commonName: "*.example.com" # CHANGE to your domain
+  dnsNames:
+    - "*.example.com" # CHANGE
+    - "example.com" # CHANGE (apex, optional)

deploy/k3s/cert-manager/cloudflare-api-token-secret.yaml

@@ -0,0 +1,17 @@
+# Cloudflare API token used by cert-manager's DNS-01 solver to prove ownership of
+# *.example.com (it creates temporary _acme-challenge TXT records).
+#
+# For a ClusterIssuer, cert-manager reads this secret from ITS OWN namespace
+# (default: cert-manager), NOT the ntunl namespace.
+#
+# Create the token in Cloudflare → My Profile → API Tokens with:
+#   Permissions: Zone : DNS : Edit   +   Zone : Zone : Read
+#   Zone Resources: Include your zone (example.com)
+apiVersion: v1
+kind: Secret
+metadata:
+  name: cloudflare-api-token
+  namespace: cert-manager
+type: Opaque
+stringData:
+  api-token: <CLOUDFLARE_API_TOKEN>

deploy/k3s/cert-manager/clusterissuer.yaml

@@ -0,0 +1,20 @@
+# Let's Encrypt issuer using Cloudflare DNS-01 (required for wildcard certs —
+# HTTP-01 cannot validate a wildcard). Switch the server to the staging URL while
+# testing to avoid rate limits:
+#   https://acme-staging-v02.api.letsencrypt.org/directory
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-cloudflare
+spec:
+  acme:
+    server: https://acme-v02.api.letsencrypt.org/directory
+    email: you@example.com # CHANGE — Let's Encrypt notifications
+    privateKeySecretRef:
+      name: letsencrypt-cloudflare-account
+    solvers:
+      - dns01:
+          cloudflare:
+            apiTokenSecretRef:
+              name: cloudflare-api-token
+              key: api-token

deploy/k3s/configmap.yaml

@@ -5,16 +5,21 @@ metadata:
   namespace: ntunl
 data:
   # Mounted at /etc/ntunl/host.json; the container reads it via NTUNL_CONFIG.
-  # Set clientDomain.domain to YOUR domain — it is used to render public URLs and
-  # must match the wildcard DNS / ingress host below.
+  # Set clientDomain.domain to YOUR domain — used to render public URLs.
+  #
+  # clientDomain.subDomains controls subdomain assignment:
+  #   - Non-empty list -> POOL mode: the host hands out a free name from this list.
+  #     Route each one (apple/banana/cherry...) to the host; no wildcard DNS needed.
+  #     This is the easy path for Cloudflare Tunnel (one public hostname per name).
+  #   - Empty list -> fully dynamic random names (needs wildcard DNS / *.domain).
   host.json: |
     {
       "tunnelHost": {
         "hostName": "*",
         "port": 8001,
         "clientDomain": {
           "domain": "example.com",
-          "subDomains": []
+          "subDomains": ["apple", "banana", "cherry", "elderberry"]
         },
         "ssl": {
           "enabled": false,

deploy/k3s/ingress.yaml

@@ -1,9 +1,11 @@
 # Traefik ingress (bundled with k3s). Replace example.com with your domain.
 #
-# DNS required:
-#   *.example.com        A/CNAME -> your k3s ingress IP   (client tunnels + proxy)
-#   tunnel.example.com   A/CNAME -> your k3s ingress IP   (client WebSocket)
-#   portal.example.com   A/CNAME -> your k3s ingress IP   (admin/user portal)
+# DNS: a single DNS-only (grey-cloud) wildcard A record covers everything —
+#   *.example.com   A   <k3s ingress/Traefik external IP>
+# It resolves portal./tunnel./ and every client subdomain. A records can't carry
+# a port, so clients use 443 (https/wss) / 80 (http); Traefik listens on those and
+# routes to ports 8002/8001/9200 by hostname. Find the IP with:
+#   kubectl -n kube-system get svc traefik -o wide
 #
 # Note: the wildcard also matches tunnel./portal., but exact host rules take
 # priority in Traefik. "tunnel" and "portal" route to those ports, not the proxy,
@@ -56,11 +58,10 @@ spec:
                 name: ntunl-host
                 port:
                   number: 9200
-  # Uncomment once you have a wildcard TLS cert in the secret below
-  # (e.g. issued by cert-manager). Required for wss:// and https:// URLs.
-  # tls:
-  #   - hosts:
-  #       - "*.example.com"
-  #       - portal.example.com
-  #       - tunnel.example.com
-  #     secretName: ntunl-wildcard-tls
+  # Wildcard TLS issued by cert-manager (see cert-manager/). The wildcard cert
+  # covers portal./tunnel./ and every client subdomain. Required for wss:// and
+  # https:// URLs.
+  tls:
+    - hosts:
+        - "*.example.com"
+      secretName: ntunl-wildcard-tls

internal/host/tunnel.go

@@ -175,14 +175,43 @@ func (h *TunnelHost) handleConn(w http.ResponseWriter, r *http.Request) {
 	h.readPump(ctx, client)
 }
 
-// assignSubdomain picks a free subdomain. If the client requested one and it is
-// not currently in use, it gets it; otherwise a random free name is generated.
-// The chosen name is marked live via a placeholder so two connections can't claim
-// it concurrently.
+// assignSubdomain picks a free subdomain and marks it live via a placeholder so
+// two connections can't claim it concurrently. Behavior depends on whether a
+// fixed pool is configured (clientDomain.subDomains):
+//
+//   - Pool mode: only names in the pool are routable (each is DNS-routed to the
+//     host). A requested name is honored if it's a free pool member; otherwise the
+//     first free pool member is assigned. Rejected when the pool is exhausted.
+//   - Fully dynamic (empty pool): a requested name is used if free; otherwise a
+//     random word+number is generated (requires wildcard DNS to be routable).
 func (h *TunnelHost) assignSubdomain(requested string) (string, error) {
 	h.mu.Lock()
 	defer h.mu.Unlock()
 
+	pool := h.settings.ClientDomain.SubDomains
+	if len(pool) > 0 {
+		// Prefer the requested name if it is a free member of the pool.
+		if requested != "" {
+			for _, name := range pool {
+				if lower(name) == lower(requested) {
+					if _, live := h.clients[lower(name)]; !live {
+						h.clients[lower(name)] = nil // placeholder
+						return name, nil
+					}
+					break // in pool but taken — fall through to next free member
+				}
+			}
+		}
+		for _, name := range pool {
+			if _, live := h.clients[lower(name)]; !live {
+				h.clients[lower(name)] = nil // placeholder
+				return name, nil
+			}
+		}
+		return "", errors.New("no subdomains available")
+	}
+
+	// Fully dynamic: requested-if-free, else a random word+number.
 	if requested != "" {
 		if _, live := h.clients[lower(requested)]; live {
 			return "", errors.New("requested subdomain already in use")