netokay

Installable NetOkay CLI. Run netokay diagnose [target] [--out <path>] to perform one bounded, read-only check. The CLI always uses the fixed https://netokay.net/ public service; the target itself is executed only by the local runner. Evidence is schema-valid, redacted, and fail-closed. The published CLI requires Node 24.

The public command surface is deliberately small:

netokay version
netokay schema
netokay diagnose [target] [--transport https|sse|wss|mcp] [--auth-token-env ENV_NAME] [--out <path>]

Omitting --transport is the existing HTTPS command path. sse, wss, and mcp require a public https:// target on effective port 443 with no userinfo, query, or fragment. SSE and WSS use fixed event/message/deadline bounds. MCP uses the official locked @modelcontextprotocol/sdk Streamable HTTP client and only observes negotiation plus advertised capability categories; it never calls Tools, Resources, Prompts, Sampling, Elicitation, or another side-effecting operation. Authentication is accepted only as --auth-token-env ENV_NAME; the variable name and value are not written to Evidence.

Transport Evidence records metadata and size buckets only. It never retains SSE data, WebSocket challenge/message bytes, HTTP response bodies, JSON-RPC bodies, authorization, cookies, or credentials.

The default output is one schema-valid EvidenceBundle on stdout, so an Agent can parse the CLI result directly without creating a file. --out is an explicit persistence option for CI, an issue attachment, or an audit; when used, it atomically publishes a new 0600 file without clobbering an existing path. This npm package is an executable-only distribution; invoke the netokay binary (or its dist/netokay.js ESM entry) rather than relying on an import library API.

Before an Agent handoff, run netokay version and inspect its JSON. Only when the capabilities array includes the literal agent_host_context_v1 may the Agent use NETOKAY_AGENT_HOST below, or describe an optional --out 0600 Evidence handoff. If the field is missing or unavailable, report Agent handoff unavailable and stop. The bundled v0.3.0 release manifest selects the exact Agent artifact; public commit/tag/prerelease assets, real host calls, and human acceptance remain separate evidence. Do not automatically download, install, or fall back to an incompatible artifact. The generic v0.3.0 netokay diagnose command remains a separate one-shot diagnostic entrypoint.

When that capability is present, an Agent host may select only one caller-declared, allowlisted marker: codex, claude_code, or cline:

NETOKAY_AGENT_HOST=<agent-host> netokay diagnose <target>

Parse stdout as the single EvidenceBundle and preserve its exit status. The resulting Evidence records the selected caller declaration and fixed kind precedence; it is not host attestation. agent_internal_runtime remains not_observed, and the CLI does not inspect an Agent's internal runtime.

Only when persistence is explicitly requested by the caller (for CI, an issue attachment, or an audit) append --out <new-evidence-path>. The path must be new and local; the CLI creates it with mode 0600 and keeps its bytes identical to stdout. Request host approval before writing it and report the complete location.

The package does not accept service, preview, proxy, certificate, or DNS overrides. At runtime it automatically follows the invoking process's HTTP_PROXY/HTTPS_PROXY/ALL_PROXY and NO_PROXY rules; on macOS it may also use static system HTTP(S) proxy settings and their exception list. A proxy route can leave the final target IP not observed, which is recorded by safe route facts without emitting proxy URLs, hosts, ports, or credentials. Control self/echo requests explicitly negotiate JSON; target HEAD requests use the neutral Accept: */* so content negotiation does not imply a JSON API. When a proxy hides the destination, target Evidence omits unobservable address counts and IP-family fields. Transport phase facts use duration_observed and only expose attempt_count with attempt_count_observed: true when the target attempt is observable; otherwise the count is omitted and the flag is false. An explicitly configured proxy that this runtime cannot execute fails before any socket is opened; it is never silently downgraded to a direct request. Local harnesses retain their own test-only dependency injection seams outside the public command surface.