bytegeist-toolbox/README.md

# ByteGeist Toolbox

ByteGeist Toolbox is a plain Node.js and Express web app that provides practical website and network inspection tools from a single browser page.

Live site: [https://toolbox.casko.dev](https://toolbox.casko.dev)

## Tools

1. Website Status Checker
   - Accepts a public HTTP or HTTPS URL.
   - Returns online status, HTTP status code, response time, redirect count, final URL, and check timestamp.

2. DNS Lookup
   - Accepts a public hostname or pasted website URL.
   - Returns A, AAAA, CNAME, MX, TXT, and NS records plus a check timestamp.

3. SSL Certificate Checker
   - Accepts a public hostname or pasted website URL.
   - Returns certificate trust status, subject, issuer, validity dates, days remaining, TLS protocol, cipher, resolved address, SHA-256 fingerprint, authorization error when present, and check timestamp.

4. HTTP Headers Checker
   - Accepts a public HTTP or HTTPS URL.
   - Returns HTTP status, redirect count, final URL, all response headers, and whether common security headers are present.
   - The header review is informational. It is not a complete website security grade.

## Technology Stack

- Plain HTML
- Plain CSS
- Plain browser JavaScript
- Node.js
- Express
- Docker and Docker Compose
- Node's built-in test runner

## Project Structure

```text
.
|-- Dockerfile
|-- docker-compose.yml
|-- LICENSE
|-- package-lock.json
|-- package.json
|-- README.md
|-- docs
|   |-- DEPLOYMENT.md
|   |-- PORTFOLIO.md
|   |-- RELEASE_CHECKLIST.md
|   `-- screenshots
|       `-- .gitkeep
|-- public
|   |-- app.js
|   |-- index.html
|   `-- styles.css
|-- src
|   |-- middleware
|   |   |-- rateLimit.js
|   |   `-- validateHostname.js
|   |-- routes
|   |   |-- dns.js
|   |   |-- headers.js
|   |   |-- ssl.js
|   |   `-- uptime.js
|   |-- server.js
|   `-- services
|       |-- dnsService.js
|       |-- headersService.js
|       |-- sslService.js
|       |-- uptimeService.js
|       `-- urlSecurityService.js
`-- tests
    |-- dnsService.test.js
    |-- headersService.test.js
    |-- sslService.test.js
    |-- urlSecurityService.test.js
    `-- validateHostname.test.js
```

## Security Controls

The code implements these controls for server-side outbound requests:

- Allows only `http:` and `https:` URLs for URL-based tools.
- Blocks credentials in submitted URLs.
- Allows only standard ports `80` and `443` for URL-based tools.
- Blocks common local hostnames including `localhost`, `.localhost`, `.local`, and `host.docker.internal`.
- Resolves hostnames before outbound requests and blocks loopback, private, link-local, unique-local, multicast, unspecified, reserved, broadcast, and carrier-grade NAT addresses.
- Revalidates every redirect destination before following it.
- Limits redirects to 5.
- Uses 5 second network timeouts for HTTP and TLS checks.
- Applies Express rate limiting of 30 requests per IP per 15 minutes on tool API routes.
- Returns safe client-facing error messages instead of raw low-level network errors.
- Uses Node DNS, Fetch, and TLS APIs without shell execution.

## Tests

Current test command:

```bash
npm test
```

Current automated test count: 62 tests.

Baseline verified result: 62 pass, 0 fail, 0 skipped.

The current `npm test` suite includes public-network integration checks for DNS, SSL, and HTTP headers. Internet access is required for the full suite as currently organized.

## Local Development

Install dependencies:

```bash
npm install
```

Run tests:

```bash
npm test
```

Start local development with nodemon:

```bash
npm run dev
```

Start without nodemon:

```bash
npm start
```

The app listens on port `3001` by default. The health endpoint is:

```text
GET /health
```

It returns JSON shaped like:

```json
{"status":"ok","service":"bytegeist-toolbox","timestamp":"2026-07-23T10:03:36.388Z"}
```

The timestamp is generated at request time.

## Docker

Build and run with Docker Compose:

```bash
docker compose up -d --build
```

Check status:

```bash
docker compose ps
docker compose logs --tail=100
```

Stop the service:

```bash
docker compose down
```

The container runs the production start command:

```bash
npm start
```

The production application port is `3001`.

## Production Deployment

Production is intended to run as a Docker Compose service named `bytegeist-toolbox` on port `3001`, behind Nginx Proxy Manager.

The Compose file attaches the application to the external Docker network:

```text
nginx-proxy-manager_default
```

Nginx Proxy Manager should proxy to:

```text
http://bytegeist-toolbox:3001
```

Do not assume the Nginx Proxy Manager container name. Confirm container names with:

```bash
docker ps
```

## Repository Workflow

The configured remotes are:

```text
origin  https://git.casko.dev/keith/bytegeist-toolbox.git
github  https://github.com/kcasko/bytegeist-toolbox.git
```

Use `origin` for the primary Gitea repository and `github` for the GitHub mirror.

## Screenshots

No screenshot image files currently exist under `docs/screenshots/`.

Expected screenshot filenames for the v1.0.0 README are:

```text
docs/screenshots/status-checker.png
docs/screenshots/dns-lookup.png
docs/screenshots/ssl-checker.png
docs/screenshots/http-headers.png
```

Add image references to this README only after those files exist.

## Current Limitations

- The automated test suite mixes local helper tests with public-network integration tests.
- DNS and network integration tests depend on external DNS and public websites being reachable.
- The HTTP Headers Checker reports common header presence only; it does not evaluate full security posture.
- The app checks public endpoints only and intentionally blocks local, private, reserved, and nonstandard-port destinations.
- Screenshots have not yet been captured for README display.

## Planned Improvements

- Split public-network integration tests from local unit tests while preserving coverage.
- Add screenshot images for all four tools.
- Add local mock-based route tests for API responses and error paths.
- Add manual release evidence for mobile screenshots and production verification.

## Author

Keith Casko