How is-a.dev Handles Cloudflare Proxying: DNS-as-Code Implementation

The is-a.dev registry toggles Cloudflare's orange-cloud proxy feature via a boolean proxied flag in each domain's JSON file, applying CF_PROXY_ON or CF_PROXY_OFF to A, AAAA, and CNAME records while enforcing strict validation rules through automated tests.

The is-a.dev project is a DNS-as-code registry where sub-domains are defined as JSON files in the domains/ directory. Cloudflare serves as the sole DNS provider, and the registry provides granular control over Cloudflare proxying—determining whether traffic is routed through Cloudflare's edge network (orange cloud) or directly to the origin (grey cloud). This architecture allows maintainers to manage DNS records programmatically while ensuring security and compliance through automated safety checks.

Cloudflare Provider Configuration

At the heart of the proxying mechanism is the DNS provider setup in dnsconfig.js. The registry instantiates Cloudflare as the DNS provider using the DNSControl DSL:

var dnsProvider = DnsProvider(NewDnsProvider("cloudflare"));

This single provider instance handles all DNS operations for the is-a.dev zone. Once configured, the script iterates through every JSON file in the domains/ directory to generate the corresponding DNS records.

The Proxied Flag Logic

Each domain JSON file contains an optional boolean field named proxied. The registry evaluates this flag to determine the proxy state for all eligible records in that domain:

var proxyState = data.proxied ? CF_PROXY_ON : CF_PROXY_OFF;

When data.proxied is true, the registry passes CF_PROXY_ON to Cloudflare, enabling the orange-cloud proxy feature. When false or undefined, it uses CF_PROXY_OFF, exposing the record directly to the internet without Cloudflare's CDN protection.

Supported Record Types for Proxying

Cloudflare's proxy feature only supports specific record types. The is-a.dev registry respects these limitations, applying the proxy state only to A, AAAA, and CNAME records.

A and AAAA Records

For IPv4 and IPv6 address records, the registry emits records with the computed proxyState:

// IPv4 records
for (var a in data.records.A) {
    records.push(A(subdomainName, IP(data.records.A[a]), proxyState));
}

// IPv6 records  
for (var aaaa in data.records.AAAA) {
    records.push(AAAA(subdomainName, data.records.AAAA[aaaa], proxyState));
}

Each IP address in the domain's JSON array receives the same proxy state, ensuring consistent routing behavior for all addresses associated with the sub-domain.

CNAME Handling via ALIAS Records

Since DNSControl uses ALIAS records to represent CNAMEs at the zone apex, the registry maps the CNAME field from the JSON to an ALIAS record with the proxy flag:

records.push(ALIAS(subdomainName, data.records.CNAME + ".", proxyState));

This allows Cloudflare to proxy CNAME targets while maintaining the correct DNS semantics for the is-a.dev zone.

URL Redirects and Forced Proxying

URL redirects represent a special case where proxying is mandatory. When a domain specifies a URL record (used for HTTP-to-HTTPS redirects or path forwarding), the registry forces CF_PROXY_ON regardless of the proxied flag:

records.push(A(subdomainName, IP("192.0.2.1"), CF_PROXY_ON));

This uses the reserved TEST-NET-1 address 192.0.2.1 as a placeholder, ensuring the redirect traffic always flows through Cloudflare's edge network where Page Rules or Workers can process the redirection logic.

Safety Checks and Validation

The repository includes a comprehensive test suite in tests/proxy.test.js that validates proxy configurations before deployment. These tests prevent misconfigurations that could break services or violate Cloudflare's terms.

Raw Domain Exemption

The raw.is-a.dev sub-domain serves a specific technical purpose and must never be proxied. The test suite enforces this restriction explicitly:

if (file === "raw.json") {
    t.true(!data.proxied, `${file}: raw.is-a.dev cannot be proxied`);
}

Any attempt to set "proxied": true in domains/raw.json causes the test suite to fail, blocking the deployment.

Required Proxy-able Records

When a user sets "proxied": true, the domain must contain at least one record type that supports proxying. The test validates that A, AAAA, or CNAME records exist:

t.true(
    hasProxiedRecord,
    `${file}: Proxied is true but there are no records that can be proxied (A, AAAA, CNAME expected)`
);

This prevents scenarios where a user enables proxying but only provides MX, TXT, or NS records, which cannot be proxied and would result in a broken configuration.

Disallowed Proxy Targets

Certain wildcard CNAME targets are explicitly forbidden from being proxied due to security or technical constraints. The test suite maintains a blocklist:

const disallowedRecords = [{ type: "CNAME", value: "*.onrender.com" }];

If a domain attempts to proxy a CNAME pointing to *.onrender.com, the test fails, preventing potential service disruptions or violations of the target platform's terms of service.

Reserved Sub-domains and Abuse Prevention

High-value sub-domains listed in util/reserved.json (such as admin, api, proxy, and www) receive special handling. These names are automatically created as proxied A records pointing to the dummy IP 192.0.2.1:

records.push(A(subdomainName, IP("192.0.2.1"), CF_PROXY_ON));

This reservation strategy prevents subdomain squatting on critical names while ensuring they resolve through Cloudflare's infrastructure, allowing future allocation without DNS propagation delays.

Summary

• DNS-as-code architecture: All domain definitions live as JSON files under domains/, processed by dnsconfig.js using the DNSControl framework.
• Boolean proxy control: The proxied field in domain JSON determines whether records use CF_PROXY_ON (orange cloud) or CF_PROXY_OFF (grey cloud).
• Record type limitations: Only A, AAAA, and CNAME records can be proxied; URL redirects force CF_PROXY_ON regardless of the flag.
• Automated validation: tests/proxy.test.js enforces rules including the raw domain exemption, required proxy-able records, and disallowed wildcard targets.
• Reserved name protection: Critical sub-domains in util/reserved.json are automatically provisioned as proxied records to prevent abuse.

Frequently Asked Questions

What happens if I set "proxied": true without any A, AAAA, or CNAME records?

The deployment will fail. The test suite in tests/proxy.test.js validates that domains with "proxied": true must contain at least one record type that supports Cloudflare proxying. If you only provide MX, TXT, or NS records, the test throws an error and blocks the pull request.

Why can't I proxy raw.is-a.dev?

The raw.is-a.dev sub-domain is explicitly exempted from proxying in the test suite. This domain typically serves raw file content or API responses that must not pass through Cloudflare's transformation layer, ensuring direct access to the origin server for specific technical use cases.

Can I proxy a CNAME pointing to *.onrender.com?

No. The registry explicitly forbids proxying CNAME records that point to *.onrender.com or other disallowed targets listed in the test configuration. This restriction prevents service disruptions and ensures compliance with the target platform's requirements regarding Cloudflare proxying.

What is the significance of the IP address 192.0.2.1 in the configuration?

The address 192.0.2.1 belongs to TEST-NET-1, a reserved IP range defined in RFC 5737 for documentation and testing purposes. The registry uses this as a placeholder IP for URL redirects and reserved sub-domains, forcing traffic through Cloudflare's proxy without exposing a real origin server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}