Merge pull request #311 from gosuda/feature/embed-dns-provider

feat(acme): add embedded authoritative DNS provider

Author: gosunuts

.agents/skills/relay-server-config/SKILL.md

@@ -16,6 +16,7 @@ Entrypoint `cmd/relay-server/main.go`, dispatched by `utils.RunCommands` (`""`/`
 | `API_PORT` | `4017` | HTTPS API + frontend (`--api-port`) |
 | `SNI_PORT` | `443` | public SNI ingress (`--sni-port`) — cannot bind unprivileged; override locally |
 | `WIREGUARD_PORT` | `51820` | (`--wireguard-port`) |
+| `EMBEDDED_DNS_PORT` | `53` | embedded authoritative DNS (`--embedded-dns-port`) — default provider; needs 53/tcp+udp and `CAP_NET_BIND_SERVICE` in containers |
 | `ADMIN_TOKEN` | empty | bearer token for admin/policy APIs (`--admin-token`) |
 | `LANDING_PAGE_ENABLED` | `false` | (`--landing-page-enabled`) |
 | `DISCOVERY` | `false` | enable gossip; needs `BOOTSTRAPS` (`--discovery`) |
@@ -27,7 +28,7 @@ Entrypoint `cmd/relay-server/main.go`, dispatched by `utils.RunCommands` (`""`/`
 | `PPROF_ENABLED` / `PPROF_ADDR` | `false` / `127.0.0.1:6060` | pprof |
 | `X402_ENABLED` / `X402_TESTNET` / `X402_PAY_TO` | `false` / `false` / empty | mounts facilitator under `/api/x402` only when enabled |
 
-DNS/ACME provider creds are also env-bound: `ACME_DNS_PROVIDER`, `CLOUDFLARE_TOKEN`, GCP (`GCP_PROJECT_ID`+aliases, `GCP_MANAGED_ZONE`+aliases), Hetzner (`HETZNER_API_TOKEN`/`HCLOUD_TOKEN`), AWS Route53 (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`/`AWS_SESSION_TOKEN`/`AWS_REGION`→defaults us-east-1 downstream/`AWS_HOSTED_ZONE_ID`/`AWS_DNSSEC_KMS_KEY_ARN`), `VULTR_API_KEY`, `NJALLA_TOKEN`, `ENS_GASLESS_ENABLED`. Never hardcode these — reference as env vars / secrets.
+Embedded DNS is the default `ACME_DNS_PROVIDER` (empty value): `EMBEDDED_DNS_PORT` (default 53). External provider creds remain env-bound: `ACME_DNS_PROVIDER`, `CLOUDFLARE_TOKEN`, GCP (`GCP_PROJECT_ID`+aliases, `GCP_MANAGED_ZONE`+aliases), Hetzner (`HETZNER_API_TOKEN`/`HCLOUD_TOKEN`), AWS Route53 (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`/`AWS_SESSION_TOKEN`/`AWS_REGION`→defaults us-east-1 downstream/`AWS_HOSTED_ZONE_ID`/`AWS_DNSSEC_KMS_KEY_ARN`), `VULTR_API_KEY`, `NJALLA_TOKEN`, `ENS_GASLESS_ENABLED` (unsupported with embedded). Never hardcode these — reference as env vars / secrets.
 
 ## Reserved API surface (types/paths.go)
 Root-host trees that must never fall through to the SPA: `types.ReservedRootPrefixes` = `/api`, `/sdk`, `/discovery`, `/v1`. x402 public paths `/x402/prepare`, `/x402/client.js`; relay facilitator `/api/x402/{supported,verify,settle}`. Discovery: `/discovery`, `/discovery/announce` (only when `DISCOVERY=true`).
@@ -37,5 +38,5 @@ Root-host trees that must never fall through to the SPA: `types.ReservedRootPref
 
 ## Config embedding & Docker
 - `config.toml` (version/protocol) and `registry.json` (default relays) are embedded via `manifest.go` and parsed in `types/types.go`.
-- `docker-compose.yml` runs `ghcr.io/gosuda/portal:2`, publishes TCP 443 + UDP WireGuard port, and passes the above env vars.
+- `docker-compose.yml` runs `ghcr.io/gosuda/portal:2`, publishes TCP 443 + TCP/UDP 53 (embedded DNS, `cap_add: NET_BIND_SERVICE`) + UDP WireGuard port, and passes the above env vars.
 - `Dockerfile`: Node 22 stage builds the frontend into `cmd/relay-server/dist/app`, then `make build-server-bin` compiles the Go relay.

.env.example

@@ -14,10 +14,17 @@ MAX_PORT=0
 UDP_ENABLED=false
 TCP_ENABLED=false
 
-# Supported managed values: cloudflare, gcloud, hetzner, njalla, route53, vultr.
+# Supported managed values: embedded (default), cloudflare, gcloud, hetzner, njalla, route53, vultr.
 # Reused for ACME DNS-01, managed A records, the relay ECH record,
-# opt-in tunnel ECH records, and optional ENS DNS automation.
-ACME_DNS_PROVIDER=
+# and opt-in tunnel ECH records.
+ACME_DNS_PROVIDER=embedded
+
+# Embedded authoritative DNS server, the default DNS provider.
+# Requires a one-time NS delegation of the base domain at the parent zone
+# (NS portal.example.com -> ns.portal.example.com + glue A to the relay IP)
+# and open 53/tcp + 53/udp.
+# ENS gasless automation (zone DNSSEC) is not supported with embedded yet.
+EMBEDDED_DNS_PORT=53
 
 # Cloudflare API token (required when ACME_DNS_PROVIDER=cloudflare)
 CLOUDFLARE_TOKEN=
@@ -48,6 +55,7 @@ NJALLA_TOKEN=
 
 # ENS gasless DNS import automation. When enabled, Portal uses ACME_DNS_PROVIDER
 # for DNSSEC and ENS TXT automation, even when certificate files are managed manually.
+# Not supported with ACME_DNS_PROVIDER=embedded yet.
 ENS_GASLESS_ENABLED=false
 
 # Admin/auth configuration. Use a long random value for production relays.

Dockerfile

@@ -39,4 +39,9 @@ ENV TZ=UTC
 
 EXPOSE 443/tcp
 EXPOSE 51820/udp
+# Embedded authoritative DNS (ACME_DNS_PROVIDER=embedded). The runtime is
+# nonroot, so binding 53 requires CAP_NET_BIND_SERVICE:
+#   docker run --cap-add NET_BIND_SERVICE -p 53:53/tcp -p 53:53/udp ...
+EXPOSE 53/tcp
+EXPOSE 53/udp
 ENTRYPOINT ["/usr/bin/relay-server"]

cmd/relay-server/main.go

@@ -58,6 +58,7 @@ type relayServerConfig struct {
 
 	ACMEDNSProvider    string
 	ENSGaslessEnabled  bool
+	EmbeddedDNSPort    int
 	CloudflareToken    string
 	GCPProjectID       string
 	GCPManagedZone     string
@@ -101,9 +102,9 @@ func runServeCommand(args []string) error {
 	utils.BoolFlagEnv(fs, &cfg.X402Testnet, "x402-testnet", false, "use Sui testnet for relay-owned x402 facilitator payments", "X402_TESTNET")
 	utils.StringFlagEnv(fs, &cfg.X402PayTo, "x402-pay-to", "", "Sui payment recipient address for relay-owned control-plane x402 resources", "X402_PAY_TO")
 
-	utils.StringFlagEnv(fs, &cfg.ACMEDNSProvider, "acme-dns-provider", "", "DNS provider for managed DNS-01/A-record sync, ECH HTTPS records, and ENS gasless DNSSEC/TXT automation (cloudflare|gcloud|hetzner|njalla|route53|vultr); leave empty to use manual fullchain.pem/privatekey.pem from IDENTITY_PATH", "ACME_DNS_PROVIDER")
+	utils.StringFlagEnv(fs, &cfg.ACMEDNSProvider, "acme-dns-provider", "", "DNS provider for managed DNS-01/A-record sync, ECH HTTPS records, and ENS gasless DNSSEC/TXT automation (embedded|cloudflare|gcloud|hetzner|njalla|route53|vultr); defaults to embedded when unset", "ACME_DNS_PROVIDER")
 	utils.BoolFlagEnv(fs, &cfg.ENSGaslessEnabled, "ens-gasless-enabled", false, "enable ENS gasless DNS import automation for the managed DNS zone and lease hostnames", "ENS_GASLESS_ENABLED")
-	utils.StringFlagEnv(fs, &cfg.CloudflareToken, "cloudflare-token", "", "Cloudflare DNS API token (required when acme-dns-provider=cloudflare)", "CLOUDFLARE_TOKEN")
+	utils.IntFlagEnv(fs, &cfg.EmbeddedDNSPort, "embedded-dns-port", 53, utils.ParsePortNumber, "listen port for the embedded authoritative DNS server (the default DNS provider); requires a one-time NS delegation of the base domain and open 53/tcp+udp", "EMBEDDED_DNS_PORT")
 	utils.StringFlagEnv(fs, &cfg.GCPProjectID, "gcp-project-id", "", "Google Cloud project id for Cloud DNS automation; auto-detected from ADC or GCE metadata when omitted", "GCP_PROJECT_ID", "GOOGLE_CLOUD_PROJECT", "GCLOUD_PROJECT", "GCE_PROJECT")
 	utils.StringFlagEnv(fs, &cfg.GCPManagedZone, "gcp-managed-zone", "", "explicit Google Cloud DNS managed zone name or numeric ID override", "GCP_MANAGED_ZONE", "GCP_ZONE", "GCE_ZONE_ID")
 	utils.StringFlagEnv(fs, &cfg.HetznerAPIToken, "hetzner-api-token", "", "Hetzner Cloud API token for DNS automation (required when acme-dns-provider=hetzner)", "HETZNER_API_TOKEN", "HCLOUD_TOKEN")
@@ -152,6 +153,7 @@ func runServeCommand(args []string) error {
 		Bool("x402_testnet", cfg.X402Testnet).
 		Bool("x402_pay_to_configured", strings.TrimSpace(cfg.X402PayTo) != "").
 		Str("acme_dns_provider", cfg.ACMEDNSProvider).
+		Int("embedded_dns_port", cfg.EmbeddedDNSPort).
 		Bool("ens_gasless_enabled", cfg.ENSGaslessEnabled).
 		Msg("configured relay server")
 
@@ -185,7 +187,7 @@ func runServer(ctx context.Context, cfg relayServerConfig) error {
 			KeyDir:             cfg.IdentityPath,
 			DNSProvider:        cfg.ACMEDNSProvider,
 			ENSGaslessEnabled:  cfg.ENSGaslessEnabled,
-			CloudflareToken:    cfg.CloudflareToken,
+			EmbeddedDNSPort:    cfg.EmbeddedDNSPort,
 			GCPProjectID:       cfg.GCPProjectID,
 			GCPManagedZone:     cfg.GCPManagedZone,
 			HetznerAPIToken:    cfg.HetznerAPIToken,

docker-compose.yml

@@ -5,9 +5,15 @@ services:
       context: .
       dockerfile: Dockerfile
     stop_grace_period: 30s
+    # Binding the default embedded DNS port 53 as a nonroot container.
+    cap_add:
+      - NET_BIND_SERVICE
     ports:
       - "443:443"
       - "${WIREGUARD_PORT:-51820}:${WIREGUARD_PORT:-51820}/udp"
+      # Embedded authoritative DNS (the default DNS provider).
+      - "${EMBEDDED_DNS_PORT:-53}:${EMBEDDED_DNS_PORT:-53}/tcp"
+      - "${EMBEDDED_DNS_PORT:-53}:${EMBEDDED_DNS_PORT:-53}/udp"
       # Uncomment for UDP backhaul, public UDP lease ports, and raw TCP lease ports as needed.
       # - "443:443/udp"
       # - "${MIN_PORT:-40000}-${MAX_PORT:-40009}:${MIN_PORT:-40000}-${MAX_PORT:-40009}/udp"
@@ -44,6 +50,7 @@ services:
 
       # TLS/ACME materials and DNS automation
       ACME_DNS_PROVIDER: ${ACME_DNS_PROVIDER:-}
+      EMBEDDED_DNS_PORT: ${EMBEDDED_DNS_PORT:-53}
       ENS_GASLESS_ENABLED: ${ENS_GASLESS_ENABLED:-false}
       CLOUDFLARE_TOKEN: ${CLOUDFLARE_TOKEN:-}
       GCP_PROJECT_ID: ${GCP_PROJECT_ID:-}

docs/src/routes/configuration/+page.md

@@ -58,8 +58,16 @@ The relay server (`relay-server`) reads configuration from environment variables
 
 | Variable | Default | Type | Description |
 |----------|---------|------|-------------|
-| `ACME_DNS_PROVIDER` | `""` | string | DNS provider for managed DNS-01/A-record sync, the relay ECH record, opt-in tunnel ECH records, and ENS gasless DNSSEC/TXT automation (`cloudflare` \| `gcloud` \| `hetzner` \| `njalla` \| `route53` \| `vultr`); leave empty to use manual `fullchain.pem`/`privatekey.pem` from `IDENTITY_PATH` |
-| `ENS_GASLESS_ENABLED` | `false` | bool | Enable ENS gasless DNS import automation for the managed DNS zone and lease hostnames |
+| `ACME_DNS_PROVIDER` | `""` | string | DNS provider for managed DNS-01/A-record sync, the relay ECH record, opt-in tunnel ECH records, and ENS gasless DNSSEC/TXT automation (`embedded` \| `cloudflare` \| `gcloud` \| `hetzner` \| `njalla` \| `route53` \| `vultr`); unset defaults to `embedded`; manual `fullchain.pem`/`privatekey.pem` in `IDENTITY_PATH` is used when present |
+| `ENS_GASLESS_ENABLED` | `false` | bool | Enable ENS gasless DNS import automation for the managed DNS zone and lease hostnames; not supported with `ACME_DNS_PROVIDER=embedded` yet |
+
+### Embedded DNS
+
+Serves the relay base domain from an authoritative DNS server embedded in the relay process, so no DNS provider API credentials are required. It is the default provider when `ACME_DNS_PROVIDER` is unset. Delegate the base domain once at the parent zone (`NS portal.example.com -> ns.portal.example.com` with glue `A` pointing at the relay public IP) and open `53/tcp` + `53/udp`. Containers running without root need `CAP_NET_BIND_SERVICE` to bind the default port. A answers for the apex and every covered name are synthesized from the relay public IPv4; ACME DNS-01 TXT and tunnel ECH HTTPS records are served directly. ENS gasless automation (zone DNSSEC) is not supported yet.
+
+| Variable | Default | Type | Description |
+|----------|---------|------|-------------|
+| `EMBEDDED_DNS_PORT` | `53` | int | Listen port for the embedded authoritative DNS server (UDP and TCP) |
 
 ### Diagnostics
 

docs/src/routes/deployment/+page.md

@@ -31,10 +31,9 @@ SNI router.
 
 - A public Linux server with Docker and Docker Compose.
 - A public hostname such as `portal.example.com`.
-- DNS `A` records for `portal.example.com` and `*.portal.example.com`.
-- Inbound `443/tcp` and `51820/udp` when the overlay is enabled.
-- A certificate covering the root and wildcard names, or a configured Portal
-  DNS provider that can issue it.
+- A one-time NS delegation at the parent zone: `NS portal.example.com -> ns.portal.example.com` with a glue `A` record pointing at the relay public IP.
+- Inbound `443/tcp`, `53/tcp` + `53/udp` for the embedded authoritative DNS, and `51820/udp` when the overlay is enabled.
+- Certificates for the root and wildcard names are issued automatically via ACME DNS-01 against the embedded authoritative DNS.
 
 ## Configuration
 
@@ -48,8 +47,12 @@ LANDING_PAGE_ENABLED=false
 DISCOVERY=false
 BOOTSTRAPS=
 
-ACME_DNS_PROVIDER=cloudflare
-CLOUDFLARE_TOKEN=replace-with-an-api-token
+# Embedded authoritative DNS is the default provider and needs no API
+# credentials once the NS delegation above is in place. External providers
+# (cloudflare, gcloud, hetzner, njalla, route53, vultr) remain available by
+# setting ACME_DNS_PROVIDER explicitly.
+ACME_DNS_PROVIDER=
+EMBEDDED_DNS_PORT=53
 ```
 
 `LANDING_PAGE_ENABLED` supplies the initial value. Changes made from the admin
@@ -80,7 +83,8 @@ Frameworks that require a live SSR server cannot be mounted as static files.
 Run those applications separately and call the Portal API over HTTPS; the API
 allows cross-origin requests. Static-export modes can use the mount directly.
 
-When `ACME_DNS_PROVIDER` is empty, place these files in `./.portal-certs`:
+To override ACME with a manually managed certificate, place these files in
+`./.portal-certs`:
 
 ```text
 fullchain.pem
@@ -109,6 +113,7 @@ The Compose stack publishes:
 | Port | Purpose |
 |---|---|
 | `443/tcp` | Portal HTTPS, SPA, APIs, and SNI tunnel ingress |
+| `53/tcp` + `53/udp` | Embedded authoritative DNS for the delegated relay zone |
 | `51820/udp` | Relay discovery overlay |
 | configured lease range | Optional UDP and raw TCP leases |
 
@@ -186,8 +191,10 @@ non-reserved client routes fall back to the selected SPA's `index.html`.
 ### Certificate Errors
 
 Confirm `PORTAL_URL` matches the certificate root hostname and inspect the
-certificate files under `IDENTITY_PATH`. With managed ACME, verify the DNS API
-token has permission to update the selected zone.
+certificate files under `IDENTITY_PATH`. With the embedded DNS provider,
+confirm the delegation is visible (`dig @<relay public IP> portal.example.com NS`)
+and that `53/tcp` + `53/udp` are reachable. With an external provider, verify
+the DNS API token has permission to update the selected zone.
 
 ### API Port 4017
 

docs/src/routes/self-hosting/+page.md

@@ -17,18 +17,23 @@ You should have a relay running and accepting tunnel connections in about 10 min
 - A Linux server with a static public IP
 - A domain name you control (e.g. `relay.example.com`)
 - Inbound `443/tcp` open for the dashboard, relay APIs, and SNI tunnel traffic
+- Inbound `53/tcp` + `53/udp` open for the embedded authoritative DNS
 
 ## Quick Start
 
 Run the relay with a single Docker command:
 
 ```bash
 mkdir -p ./relay-data
-# Put fullchain.pem and privatekey.pem in ./relay-data first, or configure ACME below.
+# Optional: place fullchain.pem/privatekey.pem in ./relay-data to use a manual
+# certificate instead of ACME.
 docker run -d \
   --name portal-relay \
   --restart unless-stopped \
+  --cap-add NET_BIND_SERVICE \
   -p 443:443 \
+  -p 53:53/tcp \
+  -p 53:53/udp \
   -e PORTAL_URL=https://relay.example.com \
   -e IDENTITY_PATH=/portal-certs \
   -e ADMIN_TOKEN="$(openssl rand -hex 32)" \
@@ -49,8 +54,13 @@ services:
   relay:
     image: ghcr.io/gosuda/portal:2
     restart: unless-stopped
+    # Binding the default embedded DNS port 53 as a nonroot container.
+    cap_add:
+      - NET_BIND_SERVICE
     ports:
       - "443:443"
+      - "53:53/tcp"
+      - "53:53/udp"
     environment:
       PORTAL_URL: https://relay.example.com
       API_PORT: "4017"
@@ -76,7 +86,7 @@ docker compose up -d
 | `SNI_PORT` | `443` | TCP SNI router port for tunnel traffic. |
 | `IDENTITY_PATH` | `./.portal-certs` | Relay state directory containing `identity.json`, `policy.json`, and TLS materials. |
 | `ADMIN_TOKEN` | | Bearer token source for relay admin and policy APIs. |
-| `LANDING_PAGE_ENABLED` | `false` | Initial dashboard landing-page visibility; admin changes persist in `policy.json`. |
+| `EMBEDDED_DNS_PORT` | `53` | Embedded authoritative DNS listen port; requires `53/tcp` + `53/udp` and `CAP_NET_BIND_SERVICE` in containers. |
 
 ## Optional: Enable Relay-Owned Sui x402 Facilitator
 
@@ -122,18 +132,25 @@ portal-relay localhost:3000
 
 ## DNS Configuration
 
-Tunnels are assigned subdomains under your relay domain (e.g. `abc123.relay.example.com`). You need a wildcard DNS record pointing to your server:
+The relay serves DNS for its own subdomains from the embedded authoritative
+server (`relay.example.com` and every name under it, including tunnel
+hostnames). Delegate the zone to the relay once from your existing DNS
+management UI:
 
 | Type | Name | Value |
 |---|---|---|
-| `A` | `*.relay.example.com` | `<your server IP>` |
-| `A` | `relay.example.com` | `<your server IP>` |
+| `NS` | `relay.example.com` | `ns.relay.example.com` |
+| `A` | `ns.relay.example.com` | `<your server IP>` (glue) |
+No wildcard record is needed: the relay synthesizes answers for every tunnel
+hostname. The nameserver name is fixed to `ns.<your relay domain>`; publish the
+matching glue `A` record at the parent zone as shown above.
 
-DNS propagation typically takes a few minutes but can take up to 48 hours depending on your provider.
+## TLS with ACME
 
-## Optional: TLS with ACME
-
-By default the relay expects you to place `fullchain.pem` and `privatekey.pem` in the `IDENTITY_PATH` directory (`.portal-certs` by default). For automatic certificate management via DNS-01 challenges, set `ACME_DNS_PROVIDER`:
+Certificates are issued automatically via ACME DNS-01 against the embedded
+authoritative DNS server — no DNS provider credentials are required once the
+delegation above is in place. To use an external DNS provider instead, set
+`ACME_DNS_PROVIDER`:
 
 ```yaml
 environment:
@@ -175,21 +192,28 @@ requires TCP `443` because Portal publishes standard HTTPS tunnel URLs.
 
 **DNS not resolving**
 
-Verify your wildcard record is live before connecting a tunnel:
+Query the relay's authoritative server directly first, then through a public
+resolver:
 
 ```bash
+dig +short @<your server IP> test.relay.example.com
 dig +short test.relay.example.com
 ```
 
-If nothing returns, check your DNS provider dashboard and allow more time for propagation.
+If the direct query works but the public one does not, the NS delegation at
+the parent zone is missing or not yet propagated. If both fail, confirm the
+relay is running and `53/tcp` + `53/udp` are open.
 
 **Firewall blocking connections**
 
-Ensure the public HTTPS port is open in your cloud provider's security group or firewall:
+Ensure the public HTTPS and DNS ports are open in your cloud provider's
+security group or firewall:
 
 ```bash
 # UFW example
 sudo ufw allow 443/tcp
+sudo ufw allow 53/tcp
+sudo ufw allow 53/udp
 ```
 
 **Certificate errors**

go.mod

@@ -22,6 +22,7 @@ require (
 	github.com/knadh/koanf/parsers/toml/v2 v2.2.0
 	github.com/knadh/koanf/providers/file v1.2.1
 	github.com/knadh/koanf/v2 v2.3.4
+	github.com/miekg/dns v1.1.72
 	github.com/montanaflynn/stats v0.9.0
 	github.com/pelletier/go-toml/v2 v2.2.4
 	github.com/prometheus/client_golang v1.23.2
@@ -118,7 +119,6 @@ require (
 	github.com/mattn/go-isatty v0.0.21 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
 	github.com/mattn/go-runewidth v0.0.19 // indirect
-	github.com/miekg/dns v1.1.72 // indirect
 	github.com/mitchellh/copystructure v1.2.0 // indirect
 	github.com/mitchellh/reflectwalk v1.0.2 // indirect
 	github.com/mr-tron/base58 v1.2.0 // indirect

plugins/portal-deploy/README.md

@@ -18,7 +18,8 @@ plugins/portal-deploy/
 │   ├── agents/openai.yaml         # Codex skill UI metadata
 │   └── references/
 │       ├── portal-cli.md
-│       └── safety-and-verification.md
+│       ├── safety-and-verification.md
+│       └── x402.md
 └── README.md
 ```