Reserved Domains in is-a.dev: How the Registry Protects Critical Subdomains

Reserved domains in is-a.dev are protected subdomains like admin, api, and www that cannot be registered by users and are automatically configured to resolve to the placeholder IP 192.0.2.1 via Cloudflare proxy.

The is-a-dev/register repository maintains this protective mechanism to prevent namespace collisions with infrastructure-critical services. By enforcing a strict reservation policy across DNS configuration, API validation, and automated testing, the registry ensures that essential subdomains remain under administrative control.

What Constitutes a Reserved Domain

Reserved domains are specific subdomain strings listed in util/reserved.json that are permanently excluded from the public registration pool. This JSON file contains a simple array of strings representing high-value names such as about, admin, api, app, blog, dev, git, mail, www, and zone.

The repository treats these names as protected resources to prevent users from claiming subdomains that could impersonate core services or disrupt platform operations. Additionally, reserved names are excluded from the util/trusted.json configuration, preventing them from being used in internal or proxy sections of domain configurations.

DNS Configuration and Safe Resolution

The dnsconfig.js file handles the technical enforcement of reserved domains at the DNS level. During zone file generation, every entry in reserved.json is added as a static A record pointing to the RFC 5737 test address 192.0.2.1, with Cloudflare proxying enabled.

var reserved = require("./util/reserved.json");

// Handle reserved domains
for (var i = 0; i < reserved.length; i++) {
  var subdomainName = reserved[i];
  // RFC 5737 test address, Cloudflare proxy enabled
  records.push(A(subdomainName, IP("192.0.2.1"), CF_PROXY_ON));
}

This configuration guarantees that reserved names resolve to a deterministic, safe address rather than user-controlled infrastructure. The zone file also includes a _zone-updated TXT record to track the last generation timestamp.

API Validation and Suffix Matching

The util/raw-api.js file exposes the reserved list publicly via the /reserved endpoint while implementing runtime validation for registration requests. When processing new domain submissions, the API checks both exact matches and suffix patterns to prevent variations like my.admin from bypassing restrictions.

const path = require('path');
const reserved = require(path.join(__dirname, 'util/reserved.json'));

function isReserved(subdomain) {
  // exact match
  if (reserved.includes(subdomain)) return true;
  // also block any name that ends with a reserved label (e.g., foo.admin)
  return reserved.some(r => subdomain.endsWith(`.${r}`));
}

If validation detects a reserved name, the API marks the response with "reserved": true or returns an error, preventing the submission from proceeding to the domain creation stage.

The public endpoint implementation allows external tools to check availability before submitting requests:

router.get("/reserved", (req, res) => {
  res.json({ reserved: true, domains: reserved });
});

Automated Testing Enforcement

The tests/json.test.js suite provides the final layer of protection by asserting that no domain configuration file in the domains/ directory uses a reserved name. These tests run continuously to catch any attempts to circumvent the reservation system through manual file uploads or pull requests.

The test logic verifies both direct matches and suffix-based violations, ensuring that patterns like foo.admin or bar.www are flagged as invalid before merging.

Summary

• Reserved domains are defined in util/reserved.json as a JSON array of protected subdomain strings including admin, api, www, and zone.
• DNS safety is enforced in dnsconfig.js by pointing all reserved names to the RFC 5737 test IP 192.0.2.1 with Cloudflare proxy enabled.
• API validation in raw-api.js checks exact matches and suffix patterns (e.g., foo.admin) to block registration attempts.
• Automated tests in tests/json.test.js prevent reserved names from appearing in the domains/ directory.

Frequently Asked Questions

How can I check if a subdomain is reserved before submitting a request?

You can query the public API endpoint at /reserved or check the util/reserved.json file directly in the repository. The API returns the complete list of reserved domains, allowing you to verify availability before preparing your registration files.

Why does is-a.dev block suffix matches like foo.admin in addition to exact matches?

The registry blocks suffix patterns to prevent namespace squatting and potential phishing attacks. If foo.admin were allowed, it could create confusion with the protected admin.is-a.dev service or be used to impersonate administrative functions through deceptive subdomains.

What happens if someone tries to register a reserved domain through a pull request?

The automated test suite in tests/json.test.js will detect the violation and fail the CI checks, preventing the merge. Additionally, if submitted through the API, the request returns an immediate error indicating the domain is reserved, stopping the process before any DNS records are generated.

Can reserved domains ever be released for public registration?

According to the source code implementation, reserved domains are permanently excluded from registration. The infrastructure treats these names as critical resources that must remain under administrative control to maintain service integrity and prevent security vulnerabilities.

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