CH-J Server Manager

# Server Diagnostics

Integrated into the Core sidebar, in the order Plugins → Server Diagnostics → Hash & Checksum. It requires no SSH session or downloaded plugin. All runtime code, tests and fixtures live in `app/`; the module has no dependency on sibling repositories. The repository has no `doc.md`, so this document and both READMEs describe the implementation.

## User workflow

Enter a hostname, IPv4, IPv6 or HTTP(S)/WS(S) URL. Bare hostnames/IPs default to HTTPS; explicit URLs retain their path, query and port during the request. Credentials in URLs, unsupported schemes, whitespace/control characters and shell-like hostnames are rejected. IPv6 literals are bracketed automatically; scoped/link-local zone identifiers are not supported by the URL parser.

Choose Auto (prefer IPv4, otherwise IPv6), IPv4, IPv6 or Both. Resolve addresses to choose a particular current answer. The overview displays all resolved answers; probes test the selected address or one address per requested family. Both families are measured independently. AAAA presence alone never implies working IPv6 connectivity.

Run Diagnostics runs DNS, ping, traceroute, HTTP, compression, TLS and the selected TCP ports. WebSocket is opt-in. Each tool also has a separate Run/Stop control. One diagnostic run may be active at once. A completed run means the tools have finished, not that every probe succeeded. There is no blanket “server offline” verdict.

Timeout, packet count, repetitions, maximum hops, DNS resolver, protocol selection, warm connection and HTTP/HTTPS comparison are configurable. Changing the target clears a previously selected IP. History can reopen, compare two reports, delete, import JSON, copy or export JSON/CSV/TXT through native Core dialogs. Light/dark/system theme applies to the diagnostics section and is saved in the existing UI configuration. CZ/DE/EN follows the application language immediately.

## Components and protocol behavior

| Component | Implementation and interpretation |
| --- | --- |
| `common.js` | Validates targets/options, limits and enum values; IDNA conversion; numeric statistics exclude unknown values. |
| `dnsDiagnostics.js` | System address resolution uses `dns.lookup` to honor OS configuration and hosts files. Record queries use bounded UDP DNS with TCP fallback for truncated responses against `dns.getServers()`, or the explicitly chosen custom/public resolver. No implicit switch to public DNS. |
| `processTools.js` | Executes OS ping/traceroute with an argument array and `shell: false`, bounded output, explicit timeout and abort/kill cleanup. Parses packet replies and hops, rather than treating process duration as RTT. |
| `httpDiagnostics.js` | Bundled curl for HTTP/1.1, HTTP/2 and HTTP/3; strict certificate verification and pinned IP family. Each version is independently requested; the actual version is recorded. |
| `socketDiagnostics.js` | Explicit TLS version probes, bounded TCP connects/passive banners, pre-authentication SSH host-key observation using the existing ssh2 dependency, and optional RFC 6455 Upgrade validation. |
| `diagnosticsService.js` | Runs and cancels tools, selects/validates addresses, streams progress, preserves partial measurements and owns the run deadline. |
| `historyStore.js` | Versioned bounded local history, redaction, schema-checked imports and measured-data exports. |

### ICMP and routes

Ping defaults to four individually executed ICMP echo requests. Results contain per-packet measured RTT, received/sent counts, loss, min/average/max, population standard deviation, mean absolute difference between consecutive measured RTTs (jitter), TTL/Hop Limit when printed, and timestamps. A `<1 ms` reply is counted as received with an upper bound, rather than inventing a numeric RTT. Unknown RTTs are excluded from latency statistics. Statistics use the retained window of at most 500 packets; sent/received/loss counts cover the whole run. Graphs show the last 200 observations, with distinct symbols for replies, sub-resolution replies, missing replies and explicit request/process timeouts.

A missing reply can reflect ICMP filtering, packet loss or timeout; these observations cannot identify a firewall conclusively. Missing executables, local permission failures and invalid tool invocations are separate tool errors, not packet loss or server unavailability. No privilege escalation is requested.

Traceroute streams hops, addresses, individual probes, means and observed unanswered-probe percentages. Reverse DNS is resolved after the route, using the selected resolver. Repetitions compare observed hop-address sequences; differences can reflect load balancing. Unanswered intermediate hops do not establish a broken route. Raw probe metadata and method appear in expandable details. macOS requires integer-second traceroute waits; the effective rounded timeout is recorded.

### DNS

The twelve record types are A, AAAA, CNAME, MX, NS, TXT, SOA, SRV, CAA, PTR, DS and DNSKEY. DNS wire parsing checks transaction/question identity, record sizes, compression-pointer loops and message limits. Answers preserve record TTLs, query timing, resolver and NXDOMAIN/NODATA/SERVFAIL/refused/timeout states. OS address lookups cannot supply TTL; the separate record query can.

CNAME following is bounded to eight links with cycle detection. Consistency repeats A/AAAA answers from the selected resolver, and performs forward-confirmed PTR for IP-literal DNS tests. Changed answers are observations, not proof of a DNS fault. Queries for SRV use the target name as given; enter a service name such as `_service._tcp.example.org` when needed. DNSSEC is always **not validated**. DS/DNSKEY presence and even a resolver's AD flag are never treated as independent validation.

### HTTP, performance and compression

HTTP/1.1 accepts that version as supported only when it was actually returned. HTTPS HTTP/2 requires negotiated h2; no fallback is relabeled. Cleartext HTTP/2 uses prior knowledge, not an HTTP/1.1 Upgrade probe. TLS verification remains strict for every HTTP/WebSocket request.

Manual redirects are limited to eight; loops, invalid destinations and excessive redirects fail explicitly. The full chain records cross-domain changes and HTTPS downgrades; schemes and www changes are visible in the source/destination URLs. Credentials and non-HTTP(S) redirect schemes are rejected. Each cross-host redirect is resolved independently through the selected resolver and requested IP family.

Measurements include DNS (when performed), TCP, TLS, final-response TTFB, overall TTFB including DNS/redirects, download, redirect and total wall time, actual entity bytes, transfer speed, status, response headers, actual server address/port, ALPN and verified connection reuse. DNS/TCP/TLS phases not performed on a pinned or reused connection are `N/A`, not fake zeros. QUIC has no TCP phase; its handshake is separately recorded. Header-transfer or full wire overhead is not asserted as entity-byte measurement. These are server/network timings, not page rendering or Lighthouse scores.

Each selected protocol uses the same target and repetitions. IPv4/IPv6 and HTTP/HTTPS are explicit comparison options. The alternate scheme uses its default port. Every protocol starts an independent bundled-client process per sample. Connection reuse is not asserted. Total-time statistics include min/average/median/max/nearest-rank P95 and a separate transport/protocol error rate; HTTP status codes remain visible even when a server successfully returns a 4xx/5xx response.

Compression sends identity, gzip, deflate, br and (when the runtime supports it) zstd as separate Accept-Encoding requests. Content-Encoding must match, and bounded decompression must succeed. A ratio is calculated only if the decoded body hash, final URL and status match the identity baseline. Ignored encodings are unsupported; changing/dynamic bodies have no ratio. This is an observation for that URL/status, not universal server support.

Security-header checks show presence and value of HSTS, CSP, X-Content-Type-Options, Referrer-Policy, Permissions-Policy and X-Frame-Options. A CSP frame-ancestors directive can supersede the latter. Presence does not establish that the policy is correctly configured or that the website is secure.

### HTTP/3 requirements and proof


HTTP/1.1, HTTP/2 and HTTP/3 use the same bundled curl client. macOS arm64 and Linux x64 use curl 8.22.0, OpenSSL 3.5.9, nghttp2 1.70.0, ngtcp2 1.25.0 and nghttp3 1.18.0. Windows x64 uses the official curl.se curl-for-win 8.22.0_3 static build with LibreSSL 4.3.3 and the same HTTP libraries. No system curl fallback, runtime download or administrator permission is needed. The Windows upstream reproducible build recipe is https://github.com/curl/curl-for-win/tree/9d77e31e .

Build with `python3 scripts/native/build.py` (Windows: `python scripts/native/build.py`) before packaging. macOS/Linux require C/C++ tools, CMake, Ninja, Perl, make and pkg-config. Sources are pinned by version and upstream SHA-256 in `scripts/native/dependencies.lock.json`. The script verifies every download, statically links third-party transport libraries and fails without HTTP2/HTTP3/SSL features. Only operating-system libraries remain dynamic. Windows uses the pinned official binary archive, not a locally compiled Windows transport stack. The bundled CA file has its own pinned hash; component licenses and upstream build provenance accompany the runtime.

The client and trust store are installed outside app.asar in `resources/native-runtime/<platform>-<arch>/`. Each diagnostic verifies component hashes, architecture and executable capabilities before use. Config files, proxies, TLS trust environment overrides and library injection variables are excluded. curl runs with an absolute path, shell disabled, verified CA trust, an explicit resolved IP family, no cookies, no automatic redirects, and bounded output and time. Redirects are validated and re-resolved by the application. HTTPS on ports other than 443 is supported.

HTTP/3 uses `--http3-only` and is confirmed only after a completed transfer reporting HTTP version 3 and successful certificate verification. HTTP error responses such as 404 can confirm the protocol. Alt-Svc is an advertisement, not proof. QUIC timeout, certificate failure, DNS failure, connection refusal, incompatible protocol and component failure remain distinct. A UDP timeout leaves server support unverified. QUIC handshake timing is not reported as TCP timing.

Every measurement starts a separate process/connection. The warm option does not claim connection reuse for the bundled client. This keeps protocol comparisons consistent. Reports include runtime versions, capabilities, TLS verification and QUIC timing, while history/export remove bodies, URL queries and authentication headers.

Update these pins and rebuild every supported platform when updating the transport stack or CA trust store. Published artifacts and source snapshots are immutable.

## Core IPC

Preload exposes only `window.chjCore.diagnostics`; all handlers retain the existing main-window sender check and network work stays in main. Results use `{ ok: true, value }` or `{ ok: false, error: { code, message } }`.

| Channel / preload method | Payload / result |
| --- | --- |
| `diagnostics:resolve` / `resolve(options)` | Validated target/settings → target and resolved addresses. At most two concurrent resolution requests. |
| `diagnostics:start` / `start(options)` | Validated target/settings/tool selection → opaque job ID and initial report. |
| `diagnostics:cancel` / `cancel(id, tool?)` | Cancel one active/queued tool or the entire run. |
| `diagnostics:get` / `get(id)` | Snapshot of a known run or saved report. |
| `diagnostics:history` / `history()` | Local history summaries. |
| `diagnostics:removeHistory` / `removeHistory(id)` | Remove the selected history item. |
| `diagnostics:copy` / `copy(id, format)` | Main writes a redacted known report to clipboard. |
| `diagnostics:export` / `export(id, format)` | JSON/CSV/TXT via native save dialog; renderer cannot supply a filesystem path. |
| `diagnostics:import` / `import()` | Native file picker, size/schema/depth validation and redaction before storing. |
| `diagnostics:progress` / `onProgress(callback)` | Resolved addresses, tool starts/completions, packets, hops, HTTP samples and completion; returns an unsubscribe callback. |

No generic shell, filesystem or network API is exposed. Context isolation, sandbox, disabled Node integration and the existing renderer CSP remain enabled. Existing plugin contracts and updater verification/exceptions are unchanged.

## Budgets and local data

- One run, two active tools, at most two IP-family probes per tool; TCP additionally limits each address to four connections.
- Per-operation timeout 250–30000 ms; 1–100 packets, 1–20 repetitions, 1–40 hops, 1–16 ports. Regular runs stop at five minutes; continuous ping at thirty minutes. The traceroute subprocess has a further 180-second cap.
- Process output normally 256 KiB; HTTP entity body 2 MiB; decompressed body 8 MiB; HTTP headers bounded; no response bodies enter history.
- Retain at most 500 packets/progress events, five in-memory runs, thirty history reports and 10 MiB of history. History uses the existing private atomic writer at `<userData>/diagnostics/history.json` (mode 0600).
- Imports are at most 2 MiB, schema 1, with bounded nesting and validated result collections. CSV cells are escaped and formula prefixes neutralized. URL queries/fragments, credentials, cookies, authentication headers and raw bodies are excluded from stored/copied/exported reports. Raw details show measured structured data, not a packet capture or retained response body.
- No cloud synchronization, automatic login, server configuration changes or aggressive/unbounded scanning. The user explicitly chooses target/ports/resolver.

## Platform requirements and verification

| Platform | ICMP | Route | Other protocols |
| --- | --- | --- | --- |
| Windows 10/11 | `ping.exe -4/-6` | `tracert.exe -4/-6`, ICMP | Bundled curl.exe with HTTP/2 and HTTP/3. Localized RTT fields do not depend on the word “time”. |
| macOS | `/sbin/ping`, `/sbin/ping6` | `/usr/sbin/traceroute`, `/usr/sbin/traceroute6`, UDP; integer-second waits | Bundled curl with HTTP/2 and HTTP/3. |
| Ubuntu/Linux | iputils `ping -4/-6` | standard `traceroute -4/-6`, UDP | Bundled curl with HTTP/2 and HTTP/3; missing ICMP/route tools are reported separately. |

No new npm dependency was added. The implementation uses Node built-ins and the application's existing ssh2. It neither installs system tools nor requests administrative rights. Firewalls and UDP restrictions can prevent a test from establishing support; they cannot be inferred from a timeout alone.

Automated coverage is in `diagnosticsCore.test.js`, `diagnosticsNetwork.test.js`, `diagnosticsHttp.test.js` and `diagnosticsIpc.test.js`: validation/IPv6 literals, native/local DNS UDP+TCP fixtures, missing/dual-family answers and resolver errors, CNAME/consistency, OS argument/parsing fixtures, bounded real child processes, blocked ICMP observations, real local HTTP/1.1 and TLS h2, redirects/body limits/timeouts/reuse, compression enabled/ignored, HTTP3 capabilities/success-result parsing/fallback rejection, local CA trust/mismatch/expiration and real IPv6 HTTP/HTTPS, TCP connect/refused/mock timeout, real WebSocket and SSH pre-authentication handshakes, cancellation/cleanup/partial results, offline state, private history round-trip/import rejection/exports, trusted IPC and preload subscriptions.

`npm test` runs deterministic tests without public test servers. `npm run test:diagnostics:ui` runs `scripts/smokeDiagnostics.js` in a graphical Electron desktop, using production UI/preload/IPC and real local HTTP/compression probes. Unrelated services are stubbed/offline only in this test harness. It checks navigation order, protocol outcomes, persistence, CZ/DE/EN, both themes, narrow-window overflow and sandbox preferences. If the shell sets ELECTRON_RUN_AS_NODE, unset it for this command.

Current runtime verification covers controlled QUIC transfers, IPv4/IPv6, HTTPS on a non-default port, 404 responses, TLS failures and a TCP-only service advertising Alt-Svc. Per-build results accompany each release.

Explicit optional limits: no independent DNSSEC validation (requires a complete validating resolver/trust-anchor lifecycle), no Lighthouse audit (server/network timing only), no deprecated TLS audit or revocation/CT service, no HTTP3 warm-reuse claim, and no HTTP/3 warm-reuse measurement. Unsupported capabilities are displayed rather than simulated.

## Files in this change

Created: the seven service files in `src/main/diagnostics/`; `src/renderer/diagnostics.js`, `diagnosticsI18n.js`, `diagnostics.css`; the four `test/diagnostics*.test.js` files; five files under `test/fixtures/diagnostics/`; `scripts/smokeDiagnostics.js`; this document.

Integrated/updated: `src/main/index.js`, `src/main/ipc/registerCoreIpc.js`, `src/preload/corePreload.js`, `src/renderer/index.html`, `app.js`, `i18n.js`, `package.json`, `app/README.md`, root `README.md`, `.gitignore` (four public fixture exceptions), and the root gitleaks allowlist narrowly naming the deliberately public TLS test-key fixture. The signing CA private key was discarded; the fixture is never used by the application runtime.