Optional fixed company diagnostic connection

This adapter adds three health reads to automatic company-agent answers. It is unconfigured by default. No credential, trust file, mount or infrastructure change is created by this source change. Ordinary automatic answers keep working without the diagnostic connection.

Cem approved the scoped read-only connection: two independent 30-day Proxmox credentials, one per host, with the pve credential also scoped to pve/601. Network Doctor owns credential/ACL setup and private installation; the application owner owns reviewed image/mount activation. Infrastructure changes outside this approved scope require Cem's approval. The pipeline performs no infrastructure operations and creates no host files or activation marker. The retained plan is diagnostic-connection-preparation/PLAN.md in the private 2026-09-25 company-agent work evidence. It is not a deployment receipt.

Fixed execution boundary #

The Bun API invokes only /usr/bin/node with one fixed argument: /opt/stech/company-agent-diagnostic-reader.cjs. The child receives an empty environment and a JSON stdin envelope containing only operation. It has no listener, shell, arbitrary command, URL, path, VMID or environment input.

The reads cover host health for pve and proxmoxdell, plus VM health for pve/601. The operation registry owns the literal GET paths; the connection loader owns the fixed addresses and DNS identities.

The DNS identities came from Network Doctor's 2026-09-25 served-certificate packet. Node uses those names for standard hostname validation and SNI, with fixed IP resolution, the host-specific CA, and the approved leaf DER SHA-256 fingerprint. It rejects redirects, compressed bodies, stale Age headers and unverified TLS. No system trust-store change is required.

Input is at most 256 bytes. Upstream bodies and child stdout/stderr are bounded to 32 KiB. Each child has a ten-second wall-clock limit and is killed on timeout or request cancellation. The Node transport also has a ten-second HTTPS limit. Provider output is projected to the existing numeric/status allowlist before stdout; the API validates and projects it again. Only fixed error codes escape; raw errors, headers, credentials and stderr are discarded.

The existing company request authorization runs before and after the read. The adapter is registered only for the configured Network Doctor organization and workspace. It imports no owner session, filesystem history or native task. Approval of an agent's proposed change remains a recorded owner decision only; this reader cannot execute it.

Exact runtime custody manifest #

The image explicitly installs Node and fixes the API/child identity to UID 1001, GID 1001 (api:nodejs). The Node executable is /usr/bin/node; the reviewed CJS bundle is root-owned mode 0444 under root-owned /opt/stech mode 0755, allowing the runtime user to traverse the directory. The actual Node version is printed during image build and must be included in runtime acceptance evidence.

Approved host source: /var/lib/stech/company-diagnostics on the accepted API host. This is a dedicated directory, outside the workspace staging volume. Mount it read-only at /run/secrets/stech-company-diagnostics in api only.

Relative file/directory	Owner	Mode	Contents
Directory itself	1001:1001	0700	Dedicated approved custody
config.json	1001:1001	0400	Version and approved public leaf fingerprints
pve-token	1001:1001	0400	Newly scoped pve credential only
proxmoxdell-token	1001:1001	0400	Independently scoped proxmoxdell credential only
pve-ca.pem	root:root or 1001:1001	0444	Approved public pve CA PEM
proxmoxdell-ca.pem	root:root or 1001:1001	0444	Approved public proxmoxdell CA PEM

All ancestors must be root/runtime-owned and not group/world-writable; symlinks are rejected. Token files must contain the complete authorization value beginning PVEAPIToken=nd-company-diag@pve!company-pilot= followed by that host's newly created secret. Other principals/token IDs are rejected. Do not reuse operator tokens or copy any credential into environment variables, commands, source or logs.

Use the closed config.json contract in loadDiagnosticConnection, with leaf fingerprints from refreshed, accepted TLS evidence. Do not add keys or use placeholder fingerprints in an installed configuration.

The host address, DNS identity, port, CA/token filenames and three operation paths are fixed in code. Missing config, Node or bundle leaves the adapter unregistered; invalid/inaccessible custody fails the read without exposing its contents.

Optional Compose activation #

The tracked optional docker-compose.company-diagnostics.yml owns the api-only read-only mount definition and refuses to create a missing host directory. It is not included in ordinary deployments without host opt-in.

Current production retains a full ordered Compose overlay chain with operator, native, recovery and private bindings. The application owner must recover and verify that observed chain and its effective configuration before cutover. After the approved directory/files exist and the reviewed image is available, append -f docker-compose.company-diagnostics.yml to that full chain, preserving its order, project identity, environment inputs, labels and existing mounts. Recreate only api through the application-owned cutover. A base-plus-workspaces command is insufficient and would drop retained bindings.

Activation is not executed by this change. Keep the existing API env_file configuration for the approved organization/workspace profile; tokens are never added to that file.

Durability: the deployment workflow owns the opt-in guard. It includes the tracked override only for production when the external marker /etc/stech/company-diagnostics.enabled exists.

The production guard prevents a shared host marker from attaching these credentials to UAT. The marker and private files are host-owned activation state outside the checkout. The hook and override ship with this source change; the host marker and custody files are not created. Deployments without the marker need no diagnostic credentials. Do not reuse the workspace staging volume for secrets. No sidecar, gateway, new VM or shared daemon change is needed.

This hook supports the normal repository workflow. It does not discover or reconcile the retained overlays currently used in production; the application owner must preserve those bindings explicitly during the production cutover.

Before installation, Network Doctor must reconcile the retained packet with this approved single-directory custody manifest and verified DNS identity plus fixed-IP/TLS-pin validation.

Validation and remaining acceptance #

bun test api/tests/company-agent-diagnostic-node.test.ts uses synthetic credentials and an owned loopback TLS fixture. It checks the closed operation input, protected files, fixed child invocation, TLS identity/pin rejection, fixed GET paths, byte limits, redaction, cancellation and deadline. It also executes the full parsed deployment shell with external commands stubbed and checks the Docker arguments for each environment/marker combination, without a live host or real marker. It does not prove deployed access.

After installation, app/ND owners must verify effective PVE token ACLs, actual container UID/mounts/Node version and bundle execution as UID 1001, all three projected reads, wrong CA/token failure, unregistered-operation rejection and requester/org/workspace isolation. Only that evidence establishes live diagnostics. For rollback, remove the opt-in and only the diagnostic override from the verified full production chain, then recreate api with every pre-existing overlay, environment input, label and mount preserved. Revoke only the new scoped tokens. Do not substitute an ordinary base-plus-workspaces composition during rollback.

Source provenance #

The HTTPS identity, pinned-address resolution, fresh socket, response decoding, byte/deadline handling and protected-path checks are narrowly ported from clean #395 commit 76fe592945a0234bf0015c00445ceabc38ca56da: api/src/lib/read-broker/{transport.ts,config.ts} and validation/error helpers from api/src/contracts/native-read-broker.ts. No dirty relay/entrypoint source, inventory endpoint, pairing protocol or generic authority framework was copied.