Authenticate plugin-owned OpenCode servers; support secured external servers (#27)

[TheRealDinghyDog]

Fixes #27 (review finding H-02).

Note

Stacked on #34 (base branch fix/issue-26-write-permissions) because both touch the same files; GitHub will retarget this PR to opencode-conversion automatically when #34 merges.

Problem

opencode serve was spawned without OPENCODE_SERVER_PASSWORD, so any local process that could reach the loopback port had full API access (file content, sessions, lifecycle) — the server itself warns about this. And the client sent no Authorization header anywhere, so a user who had secured their server got a plugin that could no longer connect.

Fix

• Owned servers: every spawn generates a per-server random password (crypto.randomBytes(24), base64url), passed only via the child environment (never argv, which is visible in the process list), with OPENCODE_SERVER_USERNAME pinned to opencode so an ambient value cannot desynchronize server and client. The credential is recorded in server.json, now written owner-only (0600).
• Client: OpencodeServerClient sends HTTP Basic auth — matching OpenCode's own convention (username defaults to opencode) — on all four paths: normal requests, fresh-connection requests, health checks, and the SSE event stream. Verified live on 1.17.15 that every route, including /global/health and /event, requires the header once a password is set.
• External servers (OPENCODE_COMPANION_SERVER_URL): credentials come from the same OPENCODE_SERVER_PASSWORD/OPENCODE_SERVER_USERNAME variables the user already exports for a secured server. A 401 now yields a precise diagnostic (missing vs. rejected credentials) instead of a generic "not healthy".
• Cancel/teardown: later processes re-derive credentials from the persisted server session or the ambient variables; teardown authenticates its dispose call, with a comment documenting that dispose only cleans instance state — PID termination remains the actual shutdown (observed live).
• Redaction: the password lives only in the child env and the 0600 server.json; status output and logs never contain it (asserted in tests).

Tests

• The fake fixture now enforces Basic auth on every route whenever a password is in its environment — so the entire existing suite runs against a password-protected server and would fail if any client path lost its header.
• New: unauthenticated HTTP and SSE requests are rejected (401) while authenticated ones work; server.json is 0600 and holds the generated credential; status --json output never contains the password; external-server matrix (no credentials → precise error, wrong password → precise error, correct password → connects, health check carries the header); buildBasicAuthHeader unit tests.
• npm test: 85 passed, 0 failed, 0 skipped.
• Live smoke test against real OpenCode 1.17.15: owned server starts password-protected (no "unsecured" warning in its log), unauthenticated health → 401, authenticated → 200, server.json mode 600, password absent from logs, teardown actually stops the listener.

🤖 Generated with Claude Code