[d3mocide]

Everything for the 0.1.0 release: the receive-only MVP, the GhostNet autopilot, the redesigned UI, 64-bit ARM support, a multi-arch release pipeline and pre-release security hardening. Design and decisions are in docs/architecture.md, which also records where the build deviates from the plan.

What's in it

• Decoder container:
  • Base and JS8Call: Ubuntu 24.04 pinned by digest, with native JS8Call 3.0.3. The AppImage is chosen per architecture (x86_64 / aarch64), each pinned by its own SHA-256, and is unpacked with unsquashfs without ever being executed.
  • Runtime: Xvfb, a PulseAudio null sink → module-remap-source → JS8Call, and a discard sink.
  • Supervision: a FATAL process exits the container with code 70. The healthcheck requires a live capture stream.
• decoder-agent: writes PCM into PulseAudio and owns the JS8Call UDP API, sending read-only requests only. It polls call activity and reports health facts.
• KiwiSDR adapter:
  • SND and W/F streams are paired under one session ID.
  • Big-endian PCM is normalized, honouring the little-endian flag.
  • Typed errors cover rejections and bad formats.
  • Only per-channel settings are ever sent.
• Bridge:
  • v1 contract (Pydantic → JSON Schema → TypeScript, with a CI drift check) and an evidence-based health state machine.
  • Binary audio/waterfall fan-out, a receiver directory, SQLite history, reconnect policy and JSON logs.
• GhostNet autopilot (opt-in, docs/ghostnet.md):
  • Follows the GhostNet v1.5 JS8 windows for one region on the nearest suitable KiwiSDR.
  • Parks on 7.107 MHz between windows.
  • Records traffic, a waterfall PNG and FLAC audio for each window.
  • Steps aside when a viewer takes control.
• Web, the "JS8 ops console":
  • Svelte 5, frosted glass over a live ASCII "signal" backdrop. Radio rings carry the callsign of each new decode.
  • Stencil ghost mark with a Share Tech Mono wordmark, and an RX mode chip (capability, not brand).
  • Waterfall, traffic, stations, map, audio monitor and health; a GhostNet panel, net log viewer and @GSTFLASH alert.
  • Responsive and accessible. No transmit control exists.
• Deploy:
  • docker-compose.yml: only web (nginx) publishes a port, on 127.0.0.1 by default. The decoder runs on an internal network with no egress.
  • Every container drops all capabilities and sets no-new-privileges.
  • Compose can pull published images (GHOSTJS8_IMAGE_PREFIX, GHOSTJS8_TAG).
• Release pipeline: a vX.Y.Z tag builds natively on amd64 and arm64 runners. Images are pushed by digest and merged into multi-arch manifests on GHCR (ghostjs8-{web,bridge,decoder}), with provenance and an SBOM.

Security review (pre-0.1.0)

A dedicated review found no high-severity issues. Every medium and low finding is fixed and tested:

• Receiver addresses:
  • Receivers chosen by viewers or the autopilot are resolved at connect time, and every address is checked. The bridge then dials the checked IP; the URL keeps the name for Host/SNI.
  • That closes 127.1/0x7f000001 tricks, internal DNS names and DNS rebinding. HTTP redirects are refused.
  • Private receivers are opt-in. The operator-configured boot receiver stays trusted.
• Error details: viewers see generic connection errors, so the bridge can't be used as a port scanner. Address refusals are terminal.
• Politeness: a station-wide floor of 5 s between receiver connects; a burst of re-selects connects only the latest choice.
• WebSocket origin: same-origin by default and port-aware. nginx now forwards $http_host; this was found by end-to-end testing through nginx.
• Kiwi password: may not contain whitespace or control characters, because it is sent inside SET auth.
• nginx: security headers apply on every location, plus a body-size limit.
• IPv6: receiver literals are bracketed correctly in URLs.

Findings along the way

• JS8Call emits RX.SPOT only when PSKReporter spotting is on, so the agent polls RX.GET_CALL_ACTIVITY instead.
• RX.DIRECTED omits the sender and appends ♢. PSKReporter and APRS spotting default to on; both are forced off.
• nginx serves .mjs as octet-stream, which breaks MapLibre's worker under nosniff. Fixed in the template.
• Upstream publishes an aarch64 AppImage but no checksums. Both architectures are pinned on first download, and the GitHub build attestation is documented.

Verification

• make check: ruff, mypy --strict, 248 pytest, eslint, prettier, svelte-check and 53 Vitest.
• make acceptance:
  • The real upstream recording goes through fake-Kiwi framing, the bridge, the agent, PulseAudio and native JS8Call; K0OG: KN4CRD SNR +02 reaches the browser WebSocket.
  • It passes on amd64 with the hardened compose settings, and on arm64 under full emulation.
  • CI now also runs it on native arm64 runners.
• make e2e: 20 Playwright tests (desktop and phone), including the axe scan, the no-transmit assertion, GhostNet, and the backdrop toggle.
• Production stack checked by hand:
  • all containers healthy with capabilities dropped;
  • security headers on /, assets, .mjs and /api;
  • same-origin WebSocket allowed and cross-site origins refused;
  • 127.1, 0x7f000001, decoder and private IPs refused as receivers.

Not done yet / follow-ups

• Live validation: against a real public KiwiSDR, and a live GhostNet window (checklist in docs/operations.md).
• Bridge features: a pool of decoder slots in one bridge, so several receivers can be decoded at once; a hold-tuning lock.
• Per-IP client limits: these need trusted X-Forwarded-For from the reverse proxy.
• First release: after merge, tag v0.1.0 to publish images.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GQHMvquKtGGkMTjMwxGrZ5