What Is internal.json in is-a.dev? Purpose and Infrastructure Protection

The internal.json file serves as the canonical registry of subdomains reserved for is-a.dev's internal infrastructure, automatically blocking user registration while configuring DNS ignore rules and API metadata for system-managed names.

The is-a.dev/register repository powers a popular free subdomain service where developers claim *.is-a.dev addresses via GitHub pull requests. At the heart of its infrastructure protection lies util/internal.json, a configuration file that explicitly defines which subdomains remain under exclusive system control to prevent conflicts with critical platform services.

Reserved Subdomains Listed in internal.json

The internal.json file contains a JSON array of infrastructure-critical subdomains that the platform treats as system-managed. These entries include:

• data
• docs
• ns1, ns2, ns3, ns4
• raw
• www

These names represent essential services—name servers, documentation sites, raw API endpoints, and the main website—that must remain available for platform operations regardless of user activity.

How internal.json Protects Infrastructure

The repository leverages internal.json across three distinct systems to ensure internal subdomains remain protected from user registration, public DNS resolution, and accidental exposure.

Blocking Contributor Registrations via Validation

The test suite enforces that no contributor can create a domain file matching an internal name. In tests/json.test.js, the validation logic imports internal.json and validates submitted filenames against the reserved list:

// tests/json.test.js
const internalDomains = require("../util/internal.json");

t.false(internalDomains.includes(subdomain),
    `${file}: Subdomain name is registered internally`);

Any pull request attempting to register docs.is-a.dev or www.is-a.dev fails automated checks immediately, preserving these names for exclusive platform use.

Excluding Subdomains from Public DNS Resolution

The DNS configuration generation process explicitly ignores all record types for internal subdomains. In dnsconfig.js, the build script appends IGNORE rules for each entry in internal.json:

// dnsconfig.js
var internal = require("./util/internal.json");

internal.forEach(function(subdomain) {
    ignored.push(IGNORE(subdomain, "*"));
});

These IGNORE rules instruct the DNS provider to drop queries for these subdomains, ensuring they remain unreachable via standard public DNS resolution and protected from accidental exposure.

Generating Internal API Entries

While hidden from public DNS, internal subdomains appear in the raw API output with standardized metadata pointing to the internal infrastructure. The util/raw-api.js script processes internal.json to generate entries mapping each reserved name to internal.is-a.dev:

// util/raw-api.js
const internal = require(path.join(__dirname, "internal.json"));

for (const subdomain of internal) {
    const commonData = {
        domain: `${subdomain}.is-a.dev`,
        subdomain,
        owner: { username: "is-a-dev" }
    };
    const records = { CNAME: "internal.is-a.dev" };
    v2.push({ ...commonData, records, internal: true });
}

This automation ensures API consumers can identify infrastructure ownership through the internal: true flag while maintaining accurate service discovery records.

Summary

• internal.json at util/internal.json defines the exclusive list of subdomains reserved for platform infrastructure, including name servers and core services.
• Registration blocking occurs through tests/json.test.js, which validates all new domain requests against the internal list and rejects conflicts.
• DNS protection happens via dnsconfig.js, where automated IGNORE rules prevent public resolution of internal names.
• API consistency is maintained by util/raw-api.js, which generates canonical CNAME records pointing internal subdomains to internal.is-a.dev with appropriate metadata flags.

Frequently Asked Questions

What happens if a contributor tries to register an internal subdomain?

The continuous integration pipeline executes tests/json.test.js, which imports internal.json and checks every submitted filename against the reserved list. If the requested subdomain matches an internal entry, the test fails with a descriptive error message stating the subdomain is registered internally, automatically blocking the pull request from merging.

Can internal subdomains resolve through public DNS?

No. According to the source code in dnsconfig.js, every subdomain listed in internal.json receives an IGNORE(subdomain, "*") rule that instructs the DNS provider to discard all queries for those names. This prevents both intentional hijacking and accidental public exposure while the platform routes these addresses through internal mechanisms.

Why do internal subdomains appear in the API output if they are hidden from DNS?

The util/raw-api.js generator explicitly includes internal entries to maintain accurate ownership records and enable service discovery. Each internal subdomain receives a CNAME record pointing to internal.is-a.dev and an internal: true boolean flag, allowing API consumers to distinguish system-managed infrastructure from user registrations while understanding their canonical configuration.

How can a new subdomain be added to the internal list?

Adding entries to util/internal.json requires repository maintainer privileges since modifications affect core infrastructure across three critical systems. The file uses a standard JSON array format, but any addition must be accompanied by corresponding updates to dependent validation logic in tests/json.test.js, DNS configuration in dnsconfig.js, and API generation in util/raw-api.js to ensure consistent protection.

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