🌐 Domain Checker

A static-first domain checking application built with semantic HTML, native CSS, vanilla JavaScript ES modules and an included native Node.js backend. The frontend publishes directly from public/ to GitHub Pages and can operate independently or delegate authoritative checks to the backend.

✨ What it does

• Accepts pasted domains, URLs, TXT files and CSV files.
• Normalises hostnames, removes duplicates and rejects unsafe input.
• Supports client, hybrid and server execution modes.
• Lets users select Automatic, Cloudflare, Google, custom DNS-over-HTTPS or backend DNS resolution.
• Supports both provider-compatible JSON DoH and RFC 8484 wire-format DoH.
• Tests the configured backend and DNS resolver from the interface.
• Blocks private, loopback, link-local, multicast, documentation and reserved DNS answers before HTTPS probing.
• Performs optional HTTPS probes using the browser or configured backend.
• The native backend follows validated redirects, records TLS certificate metadata and returns selected response headers.
• The backend supports allowlisted DNS over UDP, TCP and DNS-over-TLS without Docker.
• Supports concurrency limits, retries, rate limiting, pause, resume and stop.
• Provides search, filtering, sorting, resolver provenance and selectable result rows.
• Generates CSV and JSON reports in the browser.
• Saves only user preferences in localStorage.

🧭 Execution modes

Mode	DNS	HTTPS	Backend required
client	Browser-accessible DoH	Browser fetch()	No
hybrid	Browser DoH by default; optional backend DNS	Backend API	Yes
server	Backend API	Backend API	Yes

The default GitHub Pages deployment uses client mode and remains fully usable without a backend.

Client mode limitations

Browser security restrictions deliberately limit what JavaScript can observe:

• CORS can hide response status and headers.
• A failed browser request cannot distinguish downtime from TLS, policy, CORS or network failure.
• Browsers cannot send traditional UDP/TCP DNS queries to a user-specified server.
• TLS certificate chains, complete redirects and server headers are not generally exposed.

A failed fetch() is therefore never labelled as definitive proof that a site is dead.

🌍 DNS resolver override

The frontend offers:

Resolver	Client	Hybrid	Server
Automatic: Cloudflare → Google	✅	✅	✅
Cloudflare	✅	✅	✅
Google	✅	✅	✅
Custom DoH — RFC 8484 wire	✅*	✅*	✅**
Custom DoH — JSON API	✅*	✅*	✅**
Backend DNS — UDP/TCP/DoT	❌	✅	✅

* The custom endpoint must use HTTPS, trust a browser-recognised certificate and allow the site origin through CORS when queried directly by the browser.

** Backend custom resolvers are disabled by default and require an operator allowlist.

Every DNS result records the resolver label, transport, format, fallback attempts and execution source.

⚠️ Result interpretation

Result	Interpretation
HTTPS_READABLE	The selected execution provider obtained a readable HTTPS response.
HTTPS_OPAQUE	A browser no-CORS request completed, but details remain hidden.
DNS_ONLY	DNS resolved while HTTPS remained inconclusive or disabled.
NO_WEB_ADDRESS	No usable public A or AAAA address was returned.
NXDOMAIN	The selected resolver reported that the name does not exist.
BLOCKED_TARGET	DNS returned a private, reserved or otherwise disallowed address.
INVALID	The submitted value failed input validation.
CHECK_ERROR	A resolver, browser or backend failure prevented classification.
CANCELLED	The scan was stopped before completion.

🏗️ Repository structure

public/ is the complete production website root. Nothing outside it is required for client mode.

domain-checker/
├── public/                       # Complete GitHub Pages artefact
│   ├── index.html
│   ├── .nojekyll
│   ├── manifest.webmanifest
│   ├── css/
│   ├── icons/
│   └── js/
│       ├── adapters/
│       ├── config/
│       ├── core/
│       ├── export/
│       ├── providers/
│       │   ├── dns/
│       │   └── execution/
│       ├── services/
│       ├── storage/
│       ├── ui/
│       └── utilities/
├── backend/                      # Native Node.js API and deployment files
│   ├── src/                      # DNS, HTTPS, policy and API modules
│   ├── config/                   # Environment template
│   ├── deploy/                   # systemd, nginx and installer
│   └── README.md
├── tests/                        # Frontend and backend automated tests
├── scripts/                      # Validation and local development tools
├── docs/
│   ├── BACKEND_API.md            # Implemented backend contract
│   └── adr/                      # Architecture decision records
├── .github/workflows/            # CI and GitHub Pages deployment
├── Dockerfile                    # Optional backend container image
├── compose.yaml                  # Hardened local container deployment
├── ARCHITECTURE.md
├── CHANGELOG.md
├── README.md
└── package.json

The full component boundaries, data models, security controls and AI-agent handover rules are defined in ARCHITECTURE.md.

🚀 Local development

Requirements

• Node.js 22 or newer for repository tooling and the native backend.
• A current Chromium, Firefox or Safari browser.

Validate the repository

npm ci
npm run check

This runs formatting checks, JavaScript safety linting, 85 automated frontend/backend tests and public/ self-containment validation.

Run locally

npm run serve

Open:

http://127.0.0.1:4173/

To simulate a GitHub Pages repository path:

BASE_PATH=/domain-checker/ npm run serve

Then open:

http://127.0.0.1:4173/domain-checker/

📦 GitHub Pages deployment

1. Push the repository with main as the default branch.
2. Open Settings → Pages.
3. Set Build and deployment → Source to GitHub Actions.
4. Push to main or run the deployment workflow manually.

The workflow validates the repository and uploads only ./public as the Pages artefact.

🔌 Native backend

The repository includes the API documented in docs/BACKEND_API.md:

GET  /api/v1/health
POST /api/v1/check

### Run it without Docker:

cp backend/config/domain-checker-backend.env.example backend.env
set -a
. ./backend.env
set +a
npm run backend:start

Test it:

curl -sS http://127.0.0.1:8080/api/v1/health

Run the backend with Docker Compose:

cp backend/config/domain-checker-backend.env.example backend.env
docker compose up --build -d
docker compose ps
curl -sS http://127.0.0.1:8080/api/v1/health

The default environment example is production-safe and permits public targets only. For an explicitly allowlisted private network, start from:

cp backend/config/domain-checker-backend.private-lan.env.example backend.env

The Compose service is read-only, runs as an unprivileged user with all Linux capabilities dropped, and publishes to loopback by default. Set BACKEND_BIND_ADDRESS only when a reverse proxy on another host must reach the container. See backend/README.md for image, configuration and shutdown details.

Install it as a hardened systemd service:

sudo backend/deploy/install-native.sh

The secure default binds to loopback. Configure nginx, TLS, ALLOWED_ORIGINS, rate limits and resolver allowlists before exposing it. Full native deployment instructions are in backend/README.md.

🧪 Testing

npm test
npm run test:unit
npm run test:integration
npm run test:e2e
npm run backend:test

The suite covers:

• URL and hostname parsing;
• duplicate removal and internationalised domains;
• private and reserved IPv4/IPv6 classification;
• queue concurrency, retry, pause, resume and cancellation;
• automatic and explicit DNS provider selection;
• custom JSON and RFC 8484 wire-format DoH;
• backend health and check response normalisation;
• native API routing, CORS, request validation and secure defaults;
• UDP/TCP DNS framing and native resolver execution;
• backend redirect validation, target pinning and TLS metadata;
• client, hybrid and server execution routing;
• readable, opaque and timed-out HTTPS probes;
• CSV/JSON provenance and formula protection;
• GitHub Pages repository-subpath hosting.

Automated tests use mocks and loopback-only test services; they do not require live Internet access.

🔐 Security and privacy

• User-controlled values are rendered with safe DOM APIs rather than innerHTML.
• Submitted IP literals and private/reserved DNS answers are blocked.
• Browser and backend requests omit cookies and referrer information.
• Custom service URLs reject embedded credentials and URL fragments.
• Browser custom DoH requires HTTPS.
• Backend custom resolvers are disabled unless explicitly enabled and allowlisted.
• Backend HTTPS connections are pinned to freshly validated public addresses.
• Redirect destinations are re-resolved and revalidated before connection.
• Client probe redirects use manual handling.
• No runtime CDN dependencies are used.
• No API keys or secrets belong in public/.
• CSV output neutralises spreadsheet formulas.
• Scan history is not persisted.
• No analytics or central telemetry is enabled.

DNS queries are visible to the selected resolver. HTTPS probes are visible to target infrastructure. Hybrid and server modes also disclose submitted domains to the configured backend.

🤖 AI-assisted implementation

Agents must read, in order:

1. ARCHITECTURE.md;
2. README.md;
3. applicable ADRs;
4. docs/BACKEND_API.md for backend-facing work;
5. relevant tests;
6. modules directly involved in the change.

Architectural changes require an ADR. Behavioural changes require tests.

🗺️ Deferred work

• Authenticated API profiles suitable for public multi-user deployments.
• RDAP and broader security-header enrichment.
• Opt-in IndexedDB scan history and scan comparison.
• Table virtualisation for very large result sets.
• Browser automation with Playwright.

📄 Licence

Released under the MIT Licence.