@mriekki/project-forge 4.8.1 → 4.9.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.8.1",
+  "version": "4.9.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "aaf5d24c897b3d89b3d1791c79bed4979414ca40",
+      "revision": "fd2cf23fa9e3d4fa27e142ce3a963f51b39cba36",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/deployment/distribution.json

@@ -16,6 +16,9 @@
     {"source": "src/project_forge_deployment/box_platform.py", "destination": "tools/project-forge-deployment/project_forge_deployment/box_platform.py"},
     {"source": "src/project_forge_deployment/box_platform_assets.py", "destination": "tools/project-forge-deployment/project_forge_deployment/box_platform_assets.py"},
     {"source": "src/project_forge_deployment/box_platform_remote.py", "destination": "tools/project-forge-deployment/project_forge_deployment/box_platform_remote.py"},
+    {"source": "src/project_forge_deployment/cloudflare_api.py", "destination": "tools/project-forge-deployment/project_forge_deployment/cloudflare_api.py"},
+    {"source": "src/project_forge_deployment/cloudflare_ingress.py", "destination": "tools/project-forge-deployment/project_forge_deployment/cloudflare_ingress.py"},
+    {"source": "src/project_forge_deployment/cloudflare_ingress_remote.py", "destination": "tools/project-forge-deployment/project_forge_deployment/cloudflare_ingress_remote.py"},
     {"source": "src/project_forge_deployment/cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/cli.py"},
     {"source": "src/project_forge_deployment/doctor.py", "destination": "tools/project-forge-deployment/project_forge_deployment/doctor.py"},
     {"source": "src/project_forge_deployment/entrypoint.py", "destination": "tools/project-forge-deployment/project_forge_deployment/entrypoint.py"},
@@ -26,6 +29,7 @@
     {"source": "src/project_forge_deployment/errors.py", "destination": "tools/project-forge-deployment/project_forge_deployment/errors.py"},
     {"source": "src/project_forge_deployment/home_lab.py", "destination": "tools/project-forge-deployment/project_forge_deployment/home_lab.py"},
     {"source": "src/project_forge_deployment/image_transfer.py", "destination": "tools/project-forge-deployment/project_forge_deployment/image_transfer.py"},
+    {"source": "src/project_forge_deployment/ingress_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/ingress_cli.py"},
     {"source": "src/project_forge_deployment/keys.py", "destination": "tools/project-forge-deployment/project_forge_deployment/keys.py"},
     {"source": "src/project_forge_deployment/local_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/local_cli.py"},
     {"source": "src/project_forge_deployment/local_runtime.py", "destination": "tools/project-forge-deployment/project_forge_deployment/local_runtime.py"},
@@ -52,6 +56,7 @@
     {"source": "src/project_forge_deployment/teardown_remote.py", "destination": "tools/project-forge-deployment/project_forge_deployment/teardown_remote.py"},
     {"source": "src/project_forge_deployment/topology_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/topology_cli.py"},
     {"source": "src/project_forge_deployment/trust.py", "destination": "tools/project-forge-deployment/project_forge_deployment/trust.py"},
+    {"source": "docs/CLOUDFLARE_INGRESS.md", "destination": "docs/project-forge/CLOUDFLARE_INGRESS.md"},
     {"source": "docs/DEVELOPER_ENVIRONMENTS.md", "destination": "docs/project-forge/DEVELOPER_ENVIRONMENTS.md"},
     {"source": "docs/WORKSPACE_INSTANCES.md", "destination": "docs/project-forge/WORKSPACE_INSTANCES.md"},
     {"source": "docs/ENVIRONMENT_PROOF.md", "destination": "docs/project-forge/ENVIRONMENT_PROOF.md"},

package/assets/generated/ASSEMBLY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.8.1",
+  "version": "4.9.0",
   "components": {
     "core": {
       "revision": "a78c2482f4f559ead8efbab6c25b4b05496db735",
@@ -326,7 +326,7 @@
       ]
     },
     "deployment": {
-      "revision": "aaf5d24c897b3d89b3d1791c79bed4979414ca40",
+      "revision": "fd2cf23fa9e3d4fa27e142ce3a963f51b39cba36",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -394,6 +394,21 @@
           "destination": "tools/project-forge-deployment/project_forge_deployment/box_platform_remote.py",
           "sha256": "65de94ac4b6e980d83ce99ea55b9555aa96959c11808cce8c6ed537b27c15533"
         },
+        {
+          "source": "src/project_forge_deployment/cloudflare_api.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/cloudflare_api.py",
+          "sha256": "de383926e04f6ebb3b8fd95948b475a9dc40d8da01ff2499afbe0f3a7305d4df"
+        },
+        {
+          "source": "src/project_forge_deployment/cloudflare_ingress.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/cloudflare_ingress.py",
+          "sha256": "98c77950df1d0bba36da1244001bdd157251238778e7068be0c6c20d2683d2d4"
+        },
+        {
+          "source": "src/project_forge_deployment/cloudflare_ingress_remote.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/cloudflare_ingress_remote.py",
+          "sha256": "38688e85654090dc7f4ab634eb3b5b6aedce9f3edb695f3d62bb09789214c86e"
+        },
         {
           "source": "src/project_forge_deployment/cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/cli.py",
@@ -407,7 +422,7 @@
         {
           "source": "src/project_forge_deployment/entrypoint.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/entrypoint.py",
-          "sha256": "6b767380f502acf0763b71f46aff6efd62674e63a526ed270097efa68c320a1e"
+          "sha256": "90d241bbbfb592c0b8e6368e13d3b3b8fb6c1e3f34c5fac9fe593df4e4a5cf1d"
         },
         {
           "source": "src/project_forge_deployment/environment_cli.py",
@@ -444,6 +459,11 @@
           "destination": "tools/project-forge-deployment/project_forge_deployment/image_transfer.py",
           "sha256": "dadd1fe7724372a4ca0e04ab2280769b6c2381f0f9ae75a096f6c5a5f5add755"
         },
+        {
+          "source": "src/project_forge_deployment/ingress_cli.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/ingress_cli.py",
+          "sha256": "c70b312aacceb9e6761eafa07a534fc41ce728b2b9aef130568b399367b2640c"
+        },
         {
           "source": "src/project_forge_deployment/keys.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/keys.py",
@@ -574,6 +594,11 @@
           "destination": "tools/project-forge-deployment/project_forge_deployment/trust.py",
           "sha256": "b143fa828c3a23df3909dacfd78ae56b9ec1159628eb45261d69c0aa6ddd1a7b"
         },
+        {
+          "source": "docs/CLOUDFLARE_INGRESS.md",
+          "destination": "docs/project-forge/CLOUDFLARE_INGRESS.md",
+          "sha256": "e0d95aa8e1c204390a51a7900ef60542537c1a9d2eeb017f34920e8dcb5e8329"
+        },
         {
           "source": "docs/DEVELOPER_ENVIRONMENTS.md",
           "destination": "docs/project-forge/DEVELOPER_ENVIRONMENTS.md",

package/assets/generated/deployment/docs/CLOUDFLARE_INGRESS.md

@@ -0,0 +1,226 @@
+# Cloudflare Tunnel public ingress
+
+Status: **PARTIAL — IMPLEMENTED MECHANICS; LIVE DOMAIN/GENERATED-CONSUMER PROOF PENDING**
+
+Project Forge models Cloudflare Tunnel as optional **public ingress**, not as a deployment target or remote-management transport.
+
+The supported shape is:
+
+```text
+placement: remote-target
+adapter: remote-ssh
+exposure: public
+ingress provider: cloudflare-tunnel
+```
+
+`remote-ssh` continues to own verified workstation-to-target management. Cloudflare Tunnel owns only internet-facing application ingress.
+
+## Architecture
+
+```text
+Internet
+  -> Cloudflare edge / public DNS / HTTPS
+  -> remotely managed Cloudflare Tunnel
+  -> cloudflared container on the selected Ubuntu target
+  -> shared Project Forge caddy-net
+  -> project-forge-caddy:80
+  -> existing Project Forge application container
+```
+
+The cloudflared runtime publishes no host ports. It initiates outbound connections to Cloudflare and joins the existing shared Docker network.
+
+Public routes do **not** replace the trusted-LAN Route Registry. Each public Cloudflare hostname forwards to the shared Caddy container while setting `originRequest.httpHostHeader` to an already-owned `.local` Project Forge hostname. Caddy therefore reuses the existing Project/environment route and upstream ownership contract.
+
+Example:
+
+```text
+inventory.example.com
+  -> Cloudflare Tunnel
+  -> http://project-forge-caddy:80
+     Host: inventory-production.local
+  -> existing Caddy route
+  -> inventory Production container
+```
+
+## Shared versus Project-owned state
+
+The shared ingress scope owns:
+
+- one remotely managed Cloudflare Tunnel identity;
+- one cloudflared container;
+- the host-side tunnel token;
+- the Cloudflare account/zone/tunnel non-secret identifiers;
+- the connector Compose definition;
+- a host-side public-route ownership registry.
+
+A Project/environment public route owns:
+
+- exact `ownerRepo`, environment, app slug and route ID;
+- one exact public hostname;
+- one exact existing `.local` origin hostname;
+- one exact Cloudflare tunnel ingress rule;
+- one exact proxied Cloudflare CNAME record.
+
+Removing a Project route must preserve the shared tunnel, cloudflared runtime, Caddy platform, unrelated DNS records and unrelated Projects.
+
+## Secrets boundary
+
+The Cloudflare API token is workstation-only. It is read from:
+
+```text
+PROJECT_FORGE_CLOUDFLARE_API_TOKEN
+```
+
+The token is never accepted as a CLI argument and is not written to:
+
+- Git;
+- `PROJECT_BOOTSTRAP.json`;
+- `DEPLOYMENT_TOPOLOGY.json`;
+- the portable Project Forge developer profile;
+- the Production host;
+- command-line process arguments.
+
+The remotely managed Tunnel token is retrieved only when applying shared ingress. It is streamed through the existing verified SSH operation and written beneath the selected root-owned ingress scope. It is not printed or returned in plans/status.
+
+Re-applying shared ingress force-recreates the cloudflared container after securely replacing the token file, so refreshed Tunnel credentials are actually consumed by the running connector.
+
+## Shared runtime commands
+
+Read-only:
+
+```text
+project-forge-deploy ingress cloudflare status <target> --scope production
+project-forge-deploy ingress cloudflare doctor <target> --scope production
+```
+
+Configure/create/adopt the shared scope after the domain exists:
+
+```text
+project-forge-deploy ingress cloudflare configure <target> \
+  --scope production \
+  --zone example.com
+```
+
+The write requires:
+
+```text
+[HOST PUBLIC INGRESS WRITE]
+```
+
+The default tunnel name is:
+
+```text
+project-forge-<scope>
+```
+
+An existing tunnel is adopted only when it is remotely managed and has no application ingress rules beyond the final fail-closed `http_status:404` rule. Project Forge never silently takes over a tunnel with existing application configuration.
+
+## Project public routes
+
+Inventory:
+
+```text
+project-forge-deploy ingress cloudflare route inventory <target> --scope production
+```
+
+Register:
+
+```text
+project-forge-deploy ingress cloudflare route register <target> \
+  --scope production \
+  --owner-repo owner/repository \
+  --environment production \
+  --app-slug inventory \
+  --public-hostname inventory.example.com \
+  --origin-hostname inventory-production.local
+```
+
+Registration requires:
+
+```text
+[PUBLIC INGRESS ROUTE WRITE]
+```
+
+Remove:
+
+```text
+project-forge-deploy ingress cloudflare route remove <target> \
+  --scope production \
+  --owner-repo owner/repository \
+  --environment production \
+  --app-slug inventory
+```
+
+Removal requires:
+
+```text
+[PUBLIC INGRESS ROUTE REMOVE]
+```
+
+## Route safety
+
+Before publishing a hostname, Deployment Kit verifies:
+
+1. the selected shared Cloudflare ingress scope is ready;
+2. the exact Project/environment `.local` route already exists and owns the requested origin hostname;
+3. the public hostname is not owned by another managed Project route;
+4. the Cloudflare tunnel configuration has the expected final fail-closed 404 rule;
+5. no conflicting tunnel ingress rule exists;
+6. no conflicting DNS record exists;
+7. any existing DNS record exactly matches Project Forge's tunnel target and ownership marker.
+
+The current partial adapter intentionally supports one first-level subdomain beneath the selected zone, such as `inventory.example.com`. Deeper names such as `api.inventory.example.com` require an explicit certificate/support review rather than being silently accepted.
+
+## Domain is deliberately late-bound
+
+A Builder does not need a domain to generate or develop a Project.
+
+Bootstrap may record:
+
+```text
+exposure: public
+ingress.provider: cloudflare-tunnel
+ingress.bindingState: deferred
+```
+
+without a zone or public hostname. Once a domain is registered and active in Cloudflare, environment setup/readiness can bind the shared ingress scope and each Project can register its exact public hostname. Regeneration is not required merely to choose the domain later.
+
+The shared Cloudflare zone is environment infrastructure and should not be copied into every Project as a credential-like default. The exact application hostname remains Project/environment state.
+
+## Current cloudflared runtime
+
+The first partial implementation selects Cloudflare release `2026.10.4` and pins the actual Docker pull to the verified multi-platform image index digest:
+
+```text
+cloudflare/cloudflared:2026.10.4@sha256:c6c7ae1d5dfdcb094ad344ed68ccffc26635c9c6be80965664c33baf064b0515
+```
+
+`latest` is never used, and a mutable tag is not the final runtime identity. Promotion from `partial` to `supported` remains blocked until the package/release process and unrelated generated consumers prove this pinned artifact together with the live Cloudflare integration path.
+
+## Required live proof before support promotion
+
+At minimum:
+
+1. create/adopt a real remotely managed Tunnel without manually logging into the Ubuntu host;
+2. install cloudflared through verified Project Forge SSH and prove no inbound host/router port is required;
+3. publish a real first-level hostname and verify external HTTPS reaches the expected Project container;
+4. publish a second unrelated Project through the same shared scope and prove isolation/collision checks;
+5. remove one Project route while preserving the other Project and the shared tunnel;
+6. exercise DNS/provider failure rollback;
+7. exercise changed host/provider state and prove stale plans fail closed;
+8. prove separate logical Production/Staging scopes when both are configured;
+9. prove generated/default-branch CI and human workspace acceptance.
+
+Tunnel connector health alone is not sufficient application evidence. Final Production readiness must include an external HTTPS application probe.
+
+## Deliberate V1 exclusions
+
+- Cloudflare Access / Zero Trust identity policy;
+- wildcard DNS publication for arbitrary applications;
+- direct public router/firewall fallback;
+- automatic domain purchase or registrar mutation;
+- deeper-than-first-level public hostnames;
+- implicit adoption of existing unmanaged Tunnel/DNS rules;
+- deleting a shared Tunnel as part of normal Project tear-down.
+
+These remain separate capabilities or future decisions.

package/assets/generated/deployment/src/project_forge_deployment/cloudflare_api.py

@@ -0,0 +1,260 @@
+"""Minimal Cloudflare API client for Project Forge public-ingress orchestration.
+
+The API token is supplied by the caller and is never persisted by this module.
+Only the exact zone/tunnel/DNS surfaces needed by the Deployment Kit are exposed.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from .errors import DeploymentKitError
+
+API_BASE = "https://api.cloudflare.com/client/v4"
+
+
+class CloudflareApiError(DeploymentKitError):
+    """Cloudflare API request or response validation failure."""
+
+
+def _api_error_message(payload: Any) -> str:
+    if isinstance(payload, dict):
+        errors = payload.get("errors")
+        if isinstance(errors, list):
+            parts = []
+            for item in errors:
+                if isinstance(item, dict):
+                    code = item.get("code")
+                    message = item.get("message")
+                    if message:
+                        parts.append(f"{code}: {message}" if code is not None else str(message))
+            if parts:
+                return "; ".join(parts)
+    return "Cloudflare API returned an unsuccessful response."
+
+
+def _request(
+    method: str,
+    path: str,
+    *,
+    token: str,
+    body: dict[str, Any] | None = None,
+    query: dict[str, str | int | bool] | None = None,
+    timeout: float = 20.0,
+) -> dict[str, Any]:
+    if not isinstance(token, str) or not token.strip():
+        raise CloudflareApiError("Cloudflare API token is required.")
+    url = API_BASE + path
+    if query:
+        encoded = urllib.parse.urlencode(
+            {key: str(value).lower() if isinstance(value, bool) else str(value) for key, value in query.items()}
+        )
+        url += "?" + encoded
+    data = None
+    headers = {
+        "Authorization": f"Bearer {token.strip()}",
+        "Accept": "application/json",
+        "User-Agent": "project-forge-deployment-kit/1",
+    }
+    if body is not None:
+        data = json.dumps(body, separators=(",", ":")).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    request = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read()
+    except urllib.error.HTTPError as error:
+        try:
+            payload = json.loads(error.read().decode("utf-8", errors="replace"))
+        except (json.JSONDecodeError, UnicodeError):
+            payload = None
+        raise CloudflareApiError(
+            f"Cloudflare API {method} {path} failed with HTTP {error.code}: {_api_error_message(payload)}"
+        ) from error
+    except urllib.error.URLError as error:
+        raise CloudflareApiError(f"Cloudflare API {method} {path} could not be reached: {error.reason}") from error
+
+    try:
+        payload = json.loads(raw.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeError) as error:
+        raise CloudflareApiError(f"Cloudflare API {method} {path} returned malformed JSON.") from error
+    if not isinstance(payload, dict) or payload.get("success") is not True:
+        raise CloudflareApiError(_api_error_message(payload))
+    return payload
+
+
+def resolve_zone(token: str, zone_name: str) -> dict[str, Any]:
+    """Resolve one exact active Cloudflare zone and its owning account."""
+    if not isinstance(zone_name, str) or not zone_name.strip():
+        raise CloudflareApiError("Cloudflare zone name is required.")
+    normalized = zone_name.strip().lower().rstrip(".")
+    payload = _request(
+        "GET",
+        "/zones",
+        token=token,
+        query={"name": normalized, "status": "active", "per_page": 50},
+    )
+    result = payload.get("result")
+    if not isinstance(result, list):
+        raise CloudflareApiError("Cloudflare zone lookup returned an unexpected result.")
+    exact = [
+        item for item in result
+        if isinstance(item, dict) and str(item.get("name", "")).lower().rstrip(".") == normalized
+    ]
+    if len(exact) != 1:
+        raise CloudflareApiError(
+            f"Expected exactly one active Cloudflare zone named {normalized}; found {len(exact)}."
+        )
+    zone = exact[0]
+    account = zone.get("account")
+    if not isinstance(account, dict) or not account.get("id"):
+        raise CloudflareApiError("Cloudflare zone response did not include its account ID.")
+    if not zone.get("id"):
+        raise CloudflareApiError("Cloudflare zone response did not include its zone ID.")
+    return {
+        "zoneId": str(zone["id"]),
+        "zoneName": normalized,
+        "accountId": str(account["id"]),
+        "status": zone.get("status"),
+    }
+
+
+def list_tunnels(token: str, account_id: str, *, name: str | None = None) -> list[dict[str, Any]]:
+    query: dict[str, str | int | bool] = {"is_deleted": False, "per_page": 1000}
+    if name is not None:
+        query["name"] = name
+    payload = _request(
+        "GET",
+        f"/accounts/{urllib.parse.quote(account_id, safe='')}/cfd_tunnel",
+        token=token,
+        query=query,
+    )
+    result = payload.get("result")
+    if not isinstance(result, list):
+        raise CloudflareApiError("Cloudflare tunnel list returned an unexpected result.")
+    return [item for item in result if isinstance(item, dict)]
+
+
+def find_tunnel(token: str, account_id: str, name: str) -> dict[str, Any] | None:
+    matches = [
+        item for item in list_tunnels(token, account_id, name=name)
+        if item.get("name") == name and item.get("deleted_at") in {None, ""}
+    ]
+    if len(matches) > 1:
+        raise CloudflareApiError(f"Multiple active Cloudflare tunnels are named {name}; refusing ambiguous adoption.")
+    return matches[0] if matches else None
+
+
+def create_tunnel(token: str, account_id: str, name: str) -> dict[str, Any]:
+    payload = _request(
+        "POST",
+        f"/accounts/{urllib.parse.quote(account_id, safe='')}/cfd_tunnel",
+        token=token,
+        body={"name": name, "config_src": "cloudflare"},
+    )
+    result = payload.get("result")
+    if not isinstance(result, dict) or not result.get("id"):
+        raise CloudflareApiError("Cloudflare tunnel creation did not return a tunnel ID.")
+    if result.get("config_src") not in {None, "cloudflare"}:
+        raise CloudflareApiError("Cloudflare created a tunnel with an unexpected configuration source.")
+    return result
+
+
+def get_tunnel_token(token: str, account_id: str, tunnel_id: str) -> str:
+    payload = _request(
+        "GET",
+        f"/accounts/{urllib.parse.quote(account_id, safe='')}/cfd_tunnel/{urllib.parse.quote(tunnel_id, safe='')}/token",
+        token=token,
+    )
+    result = payload.get("result")
+    if not isinstance(result, str) or not result.strip():
+        raise CloudflareApiError("Cloudflare tunnel-token response was empty.")
+    return result.strip()
+
+
+def get_tunnel_configuration(token: str, account_id: str, tunnel_id: str) -> dict[str, Any]:
+    payload = _request(
+        "GET",
+        f"/accounts/{urllib.parse.quote(account_id, safe='')}/cfd_tunnel/{urllib.parse.quote(tunnel_id, safe='')}/configurations",
+        token=token,
+    )
+    result = payload.get("result")
+    if not isinstance(result, dict):
+        raise CloudflareApiError("Cloudflare tunnel configuration returned an unexpected result.")
+    config = result.get("config")
+    if config is None:
+        return {"ingress": [{"service": "http_status:404"}]}
+    if not isinstance(config, dict):
+        raise CloudflareApiError("Cloudflare tunnel configuration 'config' must be an object.")
+    return config
+
+
+def update_tunnel_configuration(
+    token: str,
+    account_id: str,
+    tunnel_id: str,
+    config: dict[str, Any],
+) -> dict[str, Any]:
+    payload = _request(
+        "PUT",
+        f"/accounts/{urllib.parse.quote(account_id, safe='')}/cfd_tunnel/{urllib.parse.quote(tunnel_id, safe='')}/configurations",
+        token=token,
+        body={"config": config},
+    )
+    result = payload.get("result")
+    if not isinstance(result, dict):
+        raise CloudflareApiError("Cloudflare tunnel configuration update returned an unexpected result.")
+    returned = result.get("config")
+    return returned if isinstance(returned, dict) else config
+
+
+def list_dns_records(token: str, zone_id: str, *, name: str) -> list[dict[str, Any]]:
+    payload = _request(
+        "GET",
+        f"/zones/{urllib.parse.quote(zone_id, safe='')}/dns_records",
+        token=token,
+        query={"name": name, "per_page": 100},
+    )
+    result = payload.get("result")
+    if not isinstance(result, list):
+        raise CloudflareApiError("Cloudflare DNS lookup returned an unexpected result.")
+    return [item for item in result if isinstance(item, dict)]
+
+
+def create_dns_cname(
+    token: str,
+    zone_id: str,
+    *,
+    name: str,
+    content: str,
+    comment: str,
+) -> dict[str, Any]:
+    payload = _request(
+        "POST",
+        f"/zones/{urllib.parse.quote(zone_id, safe='')}/dns_records",
+        token=token,
+        body={
+            "type": "CNAME",
+            "name": name,
+            "content": content,
+            "proxied": True,
+            "ttl": 1,
+            "comment": comment,
+        },
+    )
+    result = payload.get("result")
+    if not isinstance(result, dict) or not result.get("id"):
+        raise CloudflareApiError("Cloudflare DNS creation did not return a record ID.")
+    return result
+
+
+def delete_dns_record(token: str, zone_id: str, record_id: str) -> None:
+    _request(
+        "DELETE",
+        f"/zones/{urllib.parse.quote(zone_id, safe='')}/dns_records/{urllib.parse.quote(record_id, safe='')}",
+        token=token,
+    )