openspec-lab/openspec/changes/archive/2026-09-06-add-vpn-tunnel-proxy/specs/tunnel-proxy/spec.md

Delta for tunnel-proxy

ADDED Requirements

Requirement: Persistent SOCKS5 Tunnel

The system MUST maintain a persistent SOCKS5 proxy tunnel from the host to VPS01, listening on 127.0.0.1:1080.

Scenario: Tunnel starts on boot

• GIVEN the host boots
• WHEN systemd starts telegram-tunnel.service
• THEN the tunnel listens on 127.0.0.1:1080
• AND the SSH connection is established with key /mnt/yandex-disk/.ssh_box/timewebVPS

Scenario: Tunnel dies

• GIVEN the tunnel process exits unexpectedly
• WHEN systemd detects failure
• THEN the service restarts automatically (Restart=always)

Requirement: Tunnel Health Monitoring

The system MUST verify tunnel liveness at least every 60 seconds.

Scenario: Health check passes

• GIVEN the tunnel is running
• WHEN checking connectivity through 127.0.0.1:1080
• THEN curl through the proxy returns HTTP 200 for a known endpoint

Scenario: Health check fails

• GIVEN the tunnel is down
• WHEN the watchdog fires
• THEN a notification is raised (no routine "all ok" messages)