dsh-vpn 0.1.0

package/scripts/vpn.sh

@@ -0,0 +1,644 @@
+#!/usr/bin/env bash
+# dsh-vpn: one-shot sing-box manager.
+#
+# Usage: vpn.sh <install|status|links|uninstall> [options]
+#   install   [--protocols LIST] [--port NAME=N]... [--sni HOST] [--server ADDR] [--regenerate]
+#             [--cert self|ip] [--acme-provider letsencrypt|URL]
+#   status
+#   links     [--server ADDR]
+#   uninstall
+#
+# Protocols (comma-separated LIST; default: previous selection, else reality,hy2):
+#   reality  VLESS + Reality + Vision   TCP
+#   hy2      Hysteria2 (pinned cert)    UDP
+#   tuic     TUIC v5                    UDP
+#   anytls   AnyTLS                     TCP
+#   ss       Shadowsocks-2022           TCP+UDP
+#
+# Certificates for hy2/tuic/anytls (--cert; default: previous choice, else self):
+#   self  self-signed; hy2 links pin it, tuic/anytls links skip verification
+#   ip    Let's Encrypt IP-address certificate for --server (6-day "shortlived"
+#         profile), issued and renewed by sing-box itself via HTTP-01 on port 80;
+#         every link verifies normally
+#
+# Human-readable progress goes to stderr. The last stdout line is always
+#   DSH_VPN_RESULT=<json>
+# so the dsh plugin (or any caller) can parse the outcome.
+#
+# Runs as root. Can be used standalone:
+#   ssh my-vps 'sudo bash -s -- install --protocols reality,hy2' < vpn.sh
+
+set -Eeuo pipefail
+
+STATE_DIR=/etc/dsh-vpn
+STATE_FILE=$STATE_DIR/state.env
+CONFIG_FILE=$STATE_DIR/config.json
+CERT_DIR=$STATE_DIR/cert
+BIN=/usr/local/bin/sing-box
+UNIT=dsh-vpn
+UNIT_FILE=/etc/systemd/system/$UNIT.service
+# CN of the self-signed cert shared by the TLS-over-QUIC/TCP protocols.
+CERT_SNI=www.bing.com
+ALL_PROTOCOLS="reality hy2 tuic anytls ss"
+SS_METHOD=2022-blake3-aes-128-gcm
+ACME_DIR=$STATE_DIR/acme
+ACME_TAG=acme-ip
+CERT_WAIT_SECONDS=${CERT_WAIT_SECONDS:-150}
+
+log() { printf '[dsh-vpn] %s\n' "$*" >&2; }
+
+# Emit the machine-readable result line and exit.
+result() { printf 'DSH_VPN_RESULT=%s\n' "$1"; exit "${2:-0}"; }
+
+fail() {
+  local code=$1; shift
+  log "ERROR: $*"
+  result "{\"ok\":false,\"error\":\"$code\",\"message\":\"$(json_escape "$*")\"}" 1
+}
+
+# Messages may quote logs: drop ANSI colors and control characters, which are
+# not allowed raw inside a JSON string.
+json_escape() {
+  printf '%s' "$1" | sed -e 's/\x1b\[[0-9;]*[A-Za-z]//g' | tr '\n\t\r' '   ' | tr -d '\000-\037\177' \
+    | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g'
+}
+
+# Safety net: any unexpected failure still ends with a result line.
+trap 'fail script_error "line $LINENO: $BASH_COMMAND"' ERR
+
+# ---------------------------------------------------------------- preflight
+
+require_root() {
+  [ "$(id -u)" = 0 ] || fail not_root "must run as root (use sudo)"
+}
+
+detect_arch() {
+  case "$(uname -m)" in
+    x86_64|amd64) echo amd64 ;;
+    aarch64|arm64) echo arm64 ;;
+    armv7l) echo armv7 ;;
+    *) return 1 ;;
+  esac
+}
+
+install_deps() {
+  local missing=()
+  for c in curl tar openssl; do command -v "$c" >/dev/null || missing+=("$c"); done
+  [ ${#missing[@]} -eq 0 ] && return
+  log "installing dependencies: ${missing[*]}"
+  if command -v apt-get >/dev/null; then
+    DEBIAN_FRONTEND=noninteractive apt-get update -qq >&2
+    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq "${missing[@]}" >&2
+  elif command -v dnf >/dev/null; then dnf install -y -q "${missing[@]}" >&2
+  elif command -v yum >/dev/null; then yum install -y -q "${missing[@]}" >&2
+  elif command -v apk >/dev/null; then apk add --no-cache "${missing[@]}" >&2
+  else fail no_pkg_manager "cannot install: ${missing[*]}"
+  fi
+}
+
+require_systemd() {
+  # TODO: OpenRC (Alpine) support.
+  command -v systemctl >/dev/null && [ -d /run/systemd/system ] \
+    || fail no_systemd "systemd is required"
+}
+
+port_in_use() { ss -Hlntu 2>/dev/null | awk '{print $5}' | grep -Eq "[:.]$1\$"; }
+
+# Sets RANDOM_PORT (no subshell, so the ERR trap can't leak into a captured
+# value). Also avoids ports already handed to another protocol in this run.
+random_port() {
+  local p
+  for _ in $(seq 1 50); do
+    p=$(( (RANDOM << 15 | RANDOM) % 50000 + 10000 ))
+    port_in_use "$p" && continue
+    case " ${TAKEN_PORTS:-} " in *" $p "*) continue ;; esac
+    RANDOM_PORT=$p; return 0
+  done
+  return 1
+}
+
+public_ip() {
+  local ip
+  for url in https://api.ipify.org https://ifconfig.me https://ipv4.icanhazip.com; do
+    ip=$(curl -fsS4 --max-time 5 "$url" 2>/dev/null | tr -d '[:space:]') && [ -n "$ip" ] && { echo "$ip"; return; }
+  done
+  ip=$(curl -fsS6 --max-time 5 https://api64.ipify.org 2>/dev/null | tr -d '[:space:]') && [ -n "$ip" ] && { echo "[$ip]"; return; }
+  return 1
+}
+
+has_protocol() { case ",$PROTOCOLS," in *",$1,"*) return 0 ;; *) return 1 ;; esac; }
+
+validate_protocols() {
+  local p
+  [ -n "$1" ] || fail bad_args "no protocols selected"
+  for p in ${1//,/ }; do
+    case " $ALL_PROTOCOLS " in *" $p "*) ;; *) fail bad_args "unknown protocol: $p" ;; esac
+  done
+}
+
+# ---------------------------------------------------------------- install steps
+
+install_singbox() {
+  local arch ver url tmp
+  arch=$(detect_arch) || fail unsupported_arch "unsupported architecture: $(uname -m)"
+  # Follow the /releases/latest redirect rather than the rate-limited API.
+  ver=${SB_VERSION:-}
+  if [ -z "$ver" ]; then
+    ver=$(curl -fsSLI -o /dev/null -w '%{url_effective}' --max-time 15 \
+      https://github.com/SagerNet/sing-box/releases/latest) || fail download_failed "cannot reach github.com"
+    ver=${ver##*/tag/}
+  fi
+  [[ $ver =~ ^v?[0-9]+\.[0-9]+\.[0-9]+ ]] || fail download_failed "cannot resolve latest sing-box version"
+  ver=${ver#v}
+  if [ -x "$BIN" ] && "$BIN" version 2>/dev/null | grep -q "version $ver\$"; then
+    log "sing-box $ver already installed"; return
+  fi
+  url="https://github.com/SagerNet/sing-box/releases/download/v$ver/sing-box-$ver-linux-$arch.tar.gz"
+  log "downloading sing-box $ver ($arch)"
+  tmp=$(mktemp -d)
+  curl -fsSL --max-time 120 "$url" -o "$tmp/sb.tgz" || fail download_failed "download failed: $url"
+  tar -xzf "$tmp/sb.tgz" -C "$tmp"
+  install -m 0755 "$tmp/sing-box-$ver-linux-$arch/sing-box" "$BIN"
+  rm -rf "$tmp"
+}
+
+# Load existing state, fill in anything missing, persist.
+# Credentials and ports are generated for every protocol, selected or not, so
+# enabling one later never rotates the others.
+prepare_state() {
+  local regenerate=$1 want_sni=$2
+  mkdir -p "$STATE_DIR" "$CERT_DIR"; chmod 700 "$STATE_DIR"
+  if [ "$regenerate" != 1 ] && [ -f "$STATE_FILE" ]; then
+    local keep_protocols=${PROTOCOLS:-} keep_cert=${CERT_MODE:-} keep_provider=${ACME_PROVIDER:-}
+    # shellcheck disable=SC1090
+    . "$STATE_FILE"
+    [ -n "$keep_protocols" ] && PROTOCOLS=$keep_protocols
+    [ -n "$keep_cert" ] && CERT_MODE=$keep_cert
+    [ -n "$keep_provider" ] && ACME_PROVIDER=$keep_provider
+  fi
+  PROTOCOLS=${PROTOCOLS:-reality,hy2}
+  CERT_MODE=${CERT_MODE:-self}
+  [ -z "${NEW_CERT_IP:-}" ] || CERT_IP=$NEW_CERT_IP
+  UUID=${UUID:-$("$BIN" generate uuid)}
+  if [ -z "${REALITY_PRIVATE:-}" ]; then
+    local kp; kp=$("$BIN" generate reality-keypair)
+    REALITY_PRIVATE=$(echo "$kp" | awk '/PrivateKey/{print $2}')
+    REALITY_PUBLIC=$(echo "$kp" | awk '/PublicKey/{print $2}')
+  fi
+  SHORT_ID=${SHORT_ID:-$("$BIN" generate rand 8 --hex)}
+  HY2_PASSWORD=${HY2_PASSWORD:-$("$BIN" generate rand 16 --hex)}
+  TUIC_PASSWORD=${TUIC_PASSWORD:-$("$BIN" generate rand 16 --hex)}
+  ANYTLS_PASSWORD=${ANYTLS_PASSWORD:-$("$BIN" generate rand 16 --hex)}
+  SS_KEY=${SS_KEY:-$("$BIN" generate rand 16 --base64)}
+  REALITY_SNI=${want_sni:-${REALITY_SNI:-www.microsoft.com}}
+
+  TAKEN_PORTS=""
+  local p var
+  for p in $ALL_PROTOCOLS; do
+    var="$(echo "$p" | tr '[:lower:]' '[:upper:]')_PORT"
+    local wanted; wanted=$(port_override "$p")
+    if [ -n "$wanted" ]; then printf -v "$var" '%s' "$wanted"
+    elif [ -z "${!var:-}" ]; then
+      if ! random_port; then fail no_free_port "could not find a free port"; fi
+      printf -v "$var" '%s' "$RANDOM_PORT"
+    fi
+    TAKEN_PORTS="$TAKEN_PORTS ${!var}"
+  done
+
+  cat >"$STATE_FILE" <<EOF
+PROTOCOLS=$PROTOCOLS
+UUID=$UUID
+REALITY_PRIVATE=$REALITY_PRIVATE
+REALITY_PUBLIC=$REALITY_PUBLIC
+SHORT_ID=$SHORT_ID
+REALITY_SNI=$REALITY_SNI
+REALITY_PORT=$REALITY_PORT
+HY2_PASSWORD=$HY2_PASSWORD
+HY2_PORT=$HY2_PORT
+TUIC_PASSWORD=$TUIC_PASSWORD
+TUIC_PORT=$TUIC_PORT
+ANYTLS_PASSWORD=$ANYTLS_PASSWORD
+ANYTLS_PORT=$ANYTLS_PORT
+SS_KEY=$SS_KEY
+SS_PORT=$SS_PORT
+CERT_MODE=$CERT_MODE
+CERT_IP=${CERT_IP:-}
+ACME_PROVIDER=${ACME_PROVIDER:-letsencrypt}
+EOF
+  chmod 600 "$STATE_FILE"
+}
+
+# Rewrite just the certificate mode (used when falling back to self-signed).
+save_cert_state() {
+  sed -i -e "s|^CERT_MODE=.*|CERT_MODE=$CERT_MODE|" "$STATE_FILE"
+}
+
+# --port NAME=N overrides, collected by cmd_install.
+PORT_OVERRIDES=""
+port_override() {
+  local kv
+  for kv in $PORT_OVERRIDES; do
+    [ "${kv%%=*}" = "$1" ] && { echo "${kv#*=}"; return; }
+  done
+  return 0
+}
+
+write_cert() {
+  [ -f "$CERT_DIR/cert.pem" ] && return
+  log "generating self-signed certificate"
+  openssl ecparam -genkey -name prime256v1 -out "$CERT_DIR/key.pem" 2>/dev/null
+  openssl req -new -x509 -days 36500 -key "$CERT_DIR/key.pem" -out "$CERT_DIR/cert.pem" \
+    -subj "/CN=$CERT_SNI" 2>/dev/null
+  chmod 600 "$CERT_DIR/key.pem"
+}
+
+cert_tls() {
+  if [ "$CERT_MODE" = ip ]; then
+    printf '{ "enabled": true, "alpn": [%s], "certificate_provider": "%s" }' "$1" "$ACME_TAG"
+  else
+    printf '{ "enabled": true, "alpn": [%s], "certificate_path": "%s", "key_path": "%s" }' \
+      "$1" "$CERT_DIR/cert.pem" "$CERT_DIR/key.pem"
+  fi
+}
+
+uses_cert() { has_protocol hy2 || has_protocol tuic || has_protocol anytls; }
+
+is_ip_literal() { [[ $1 =~ ^[0-9]{1,3}(\.[0-9]{1,3}){3}$ || $1 == *:* ]]; }
+
+# Sets ACME_CERT to the issued certificate for CERT_IP, or empty. Never fails
+# (no subshell), so it is safe under the ERR trap.
+find_acme_cert() {
+  ACME_CERT=""
+  [ -d "$ACME_DIR" ] || return 0
+  local f
+  while IFS= read -r f; do
+    # openssl prints IPv6 SANs expanded, so only IPv4 is matched exactly.
+    if [[ $CERT_IP == *:* ]] || openssl x509 -in "$f" -noout -ext subjectAltName 2>/dev/null | grep -q "IP Address:$CERT_IP\$"; then
+      ACME_CERT=$f; return 0
+    fi
+  done < <(find "$ACME_DIR" -name '*.crt' -type f 2>/dev/null)
+  return 0
+}
+
+# Anything other than our own sing-box listening on TCP 80 blocks HTTP-01.
+port80_blocker() {
+  ss -Hltnp 'sport = :80' 2>/dev/null | grep -v '"sing-box"' | grep -o 'users:(("[^"]*"' | cut -d'"' -f2 | sort -u | tr '\n' ' ' || true
+}
+
+wait_for_cert() {
+  local waited=0
+  log "waiting for the IP certificate (HTTP-01 on port 80)"
+  while [ "$waited" -lt "$CERT_WAIT_SECONDS" ]; do
+    find_acme_cert
+    [ -n "$ACME_CERT" ] && { log "certificate issued"; return 0; }
+    sleep 3; waited=$((waited + 3))
+  done
+  return 1
+}
+
+# Keep the node working: switch back to the self-signed certificate and
+# remember why, so install can report it.
+cert_fallback() {
+  local why
+  why=$(journalctl -u "$UNIT" --since "-10min" --no-pager -o cat 2>/dev/null \
+    | grep -iE 'acme|challenge|obtain|certificate' | tail -2 | tr '\n' ' ' | tail -c 800 || true)
+  log "IP certificate failed; falling back to self-signed: $why"
+  CERT_MODE=self
+  save_cert_state
+  write_config
+  write_unit
+  CERT_FAILURE="IP certificate for $CERT_IP was not issued within ${CERT_WAIT_SECONDS}s (is TCP port 80 open to the internet?); fell back to self-signed. $why"
+}
+
+# sing-box's ACME provider (certmagic) solves HTTP-01 itself on port 80 and
+# renews in the background; TLS-ALPN is off so port 443 stays untouched.
+cert_providers_json() {
+  [ "$CERT_MODE" = ip ] && uses_cert || return 0
+  local provider=$ACME_PROVIDER
+  [ "$provider" = letsencrypt ] || provider=$(json_escape "$provider")
+  printf '  "certificate_providers": [{\n'
+  printf '    "type": "acme", "tag": "%s", "domain": ["%s"], "data_directory": "%s",\n' "$ACME_TAG" "$CERT_IP" "$ACME_DIR"
+  printf '    "provider": "%s", "profile": "shortlived", "disable_tls_alpn_challenge": true\n' "$provider"
+  printf '  }],\n'
+}
+
+inbound_json() {
+  case "$1" in
+    reality) cat <<EOF
+{
+  "type": "vless", "tag": "reality", "listen": "::", "listen_port": $REALITY_PORT,
+  "users": [{ "uuid": "$UUID", "flow": "xtls-rprx-vision" }],
+  "tls": {
+    "enabled": true, "server_name": "$REALITY_SNI",
+    "reality": {
+      "enabled": true,
+      "handshake": { "server": "$REALITY_SNI", "server_port": 443 },
+      "private_key": "$REALITY_PRIVATE", "short_id": ["$SHORT_ID"]
+    }
+  }
+}
+EOF
+    ;;
+    hy2) cat <<EOF
+{
+  "type": "hysteria2", "tag": "hy2", "listen": "::", "listen_port": $HY2_PORT,
+  "users": [{ "password": "$HY2_PASSWORD" }],
+  "tls": $(cert_tls '"h3"')
+}
+EOF
+    ;;
+    tuic) cat <<EOF
+{
+  "type": "tuic", "tag": "tuic", "listen": "::", "listen_port": $TUIC_PORT,
+  "users": [{ "uuid": "$UUID", "password": "$TUIC_PASSWORD" }],
+  "congestion_control": "bbr",
+  "tls": $(cert_tls '"h3"')
+}
+EOF
+    ;;
+    anytls) cat <<EOF
+{
+  "type": "anytls", "tag": "anytls", "listen": "::", "listen_port": $ANYTLS_PORT,
+  "users": [{ "name": "dsh", "password": "$ANYTLS_PASSWORD" }],
+  "tls": $(cert_tls '')
+}
+EOF
+    ;;
+    ss) cat <<EOF
+{
+  "type": "shadowsocks", "tag": "ss", "listen": "::", "listen_port": $SS_PORT,
+  "method": "$SS_METHOD", "password": "$SS_KEY"
+}
+EOF
+    ;;
+  esac
+}
+
+write_config() {
+  local p first=1
+  {
+    printf '{\n  "log": { "level": "warn", "timestamp": true },\n'
+    cert_providers_json
+    printf '  "inbounds": [\n'
+    for p in $ALL_PROTOCOLS; do
+      has_protocol "$p" || continue
+      [ $first = 1 ] || printf ',\n'
+      first=0
+      inbound_json "$p"
+    done
+    printf '\n  ],\n  "outbounds": [{ "type": "direct", "tag": "direct" }]\n}\n'
+  } >"$CONFIG_FILE"
+  chmod 600 "$CONFIG_FILE"
+  "$BIN" check -c "$CONFIG_FILE" >&2 || fail bad_config "sing-box rejected the generated config"
+}
+
+write_unit() {
+  cat >"$UNIT_FILE" <<EOF
+[Unit]
+Description=dsh-vpn (sing-box)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=$BIN run -c $CONFIG_FILE
+Restart=on-failure
+RestartSec=3
+LimitNOFILE=1048576
+
+[Install]
+WantedBy=multi-user.target
+EOF
+  systemctl daemon-reload
+  systemctl enable "$UNIT" >/dev/null 2>&1
+  systemctl restart "$UNIT"
+  sleep 1
+  systemctl is-active --quiet "$UNIT" || {
+    journalctl -u "$UNIT" -n 20 --no-pager >&2 || true
+    fail service_failed "service failed to start"
+  }
+}
+
+# Transport(s) each protocol listens on.
+protocol_transports() {
+  case "$1" in
+    reality|anytls) echo tcp ;;
+    hy2|tuic) echo udp ;;
+    ss) echo "tcp udp" ;;
+  esac
+}
+
+protocol_port() { local var; var="$(echo "$1" | tr '[:lower:]' '[:upper:]')_PORT"; echo "${!var}"; }
+
+open_firewall() {
+  local p t rules=()
+  for p in $ALL_PROTOCOLS; do
+    has_protocol "$p" || continue
+    for t in $(protocol_transports "$p"); do rules+=("$(protocol_port "$p")/$t"); done
+  done
+  [ "$CERT_MODE" = ip ] && uses_cert && rules+=("80/tcp")
+  if command -v ufw >/dev/null && ufw status 2>/dev/null | grep -q 'Status: active'; then
+    log "opening ports in ufw: ${rules[*]}"
+    for r in "${rules[@]}"; do ufw allow "$r" >/dev/null; done
+  elif command -v firewall-cmd >/dev/null && firewall-cmd --state >/dev/null 2>&1; then
+    log "opening ports in firewalld: ${rules[*]}"
+    for r in "${rules[@]}"; do firewall-cmd -q --permanent --add-port="$r"; done
+    firewall-cmd -q --reload
+  fi
+  # TODO: raw iptables/nftables; cloud security groups must still be opened by the user.
+}
+
+enable_bbr() {
+  sysctl -n net.ipv4.tcp_congestion_control 2>/dev/null | grep -q bbr && return
+  modprobe tcp_bbr 2>/dev/null || true
+  grep -q bbr /proc/sys/net/ipv4/tcp_available_congestion_control 2>/dev/null || return
+  log "enabling BBR"
+  cat >/etc/sysctl.d/99-dsh-vpn.conf <<EOF
+net.core.default_qdisc=fq
+net.ipv4.tcp_congestion_control=bbr
+EOF
+  sysctl --system >/dev/null 2>&1 || true
+}
+
+# ---------------------------------------------------------------- output
+
+# --server (domain or IP for NAT/CDN setups) overrides detection.
+resolve_ip() {
+  if [ -n "${SERVER_OVERRIDE:-}" ]; then
+    case "$SERVER_OVERRIDE" in *:*) SERVER_IP="[$SERVER_OVERRIDE]" ;; *) SERVER_IP=$SERVER_OVERRIDE ;; esac
+    return
+  fi
+  SERVER_IP=$(public_ip) || fail no_public_ip "could not detect public IP"
+}
+
+b64url() { openssl base64 -A | tr '+/' '-_' | tr -d '='; }
+
+# One {"id","port","link",...} object per selected protocol.
+# Caller must set SERVER_IP first (see resolve_ip) so failures are not
+# swallowed by the command substitution around links_json.
+links_json() {
+  local ip=$SERVER_IP items=() p sni q_hy2 q_tuic q_anytls insecure pins=""
+  if [ "$CERT_MODE" = ip ] && uses_cert; then
+    # Publicly trusted certificate for the IP itself: clients verify normally.
+    sni=${ip#[}; sni=${sni%]}
+    q_hy2="insecure=0"; q_tuic="allow_insecure=0"; q_anytls="insecure=0"; insecure=false
+  else
+    # Hysteria2 links pin the self-signed cert (hex, `pinSHA256`); sing-box client
+    # configs need the base64 public-key hash (`certificate_public_key_sha256`).
+    # TUIC/AnyTLS links have no widely supported pin parameter, so clients must
+    # skip verification (flagged as insecure).
+    local pin spki
+    pin=$(openssl x509 -in "$CERT_DIR/cert.pem" -outform DER | sha256sum | awk '{print $1}')
+    spki=$(openssl x509 -in "$CERT_DIR/cert.pem" -pubkey -noout | openssl pkey -pubin -outform der \
+      | openssl dgst -sha256 -binary | openssl enc -base64)
+    sni=$CERT_SNI
+    q_hy2="insecure=0&pinSHA256=$pin"; q_tuic="allow_insecure=1&insecure=1"; q_anytls="insecure=1&allowInsecure=1"; insecure=true
+    pins=",\"cert_sha256\":\"$pin\",\"pubkey_sha256\":\"$spki\""
+  fi
+  for p in $ALL_PROTOCOLS; do
+    has_protocol "$p" || continue
+    case "$p" in
+      reality) items+=("$(printf '{"id":"reality","port":%s,"sni":"%s","link":"%s"}' "$REALITY_PORT" "$REALITY_SNI" \
+        "vless://$UUID@$ip:$REALITY_PORT?encryption=none&flow=xtls-rprx-vision&security=reality&sni=$REALITY_SNI&fp=chrome&pbk=$REALITY_PUBLIC&sid=$SHORT_ID&type=tcp#dsh-reality")") ;;
+      hy2) items+=("$(printf '{"id":"hy2","port":%s,"insecure":false%s,"link":"%s"}' "$HY2_PORT" "$pins" \
+        "hysteria2://$HY2_PASSWORD@$ip:$HY2_PORT?sni=$sni&alpn=h3&$q_hy2#dsh-hy2")") ;;
+      tuic) items+=("$(printf '{"id":"tuic","port":%s,"insecure":%s%s,"link":"%s"}' "$TUIC_PORT" "$insecure" "$pins" \
+        "tuic://$UUID:$TUIC_PASSWORD@$ip:$TUIC_PORT?congestion_control=bbr&udp_relay_mode=native&alpn=h3&sni=$sni&$q_tuic#dsh-tuic")") ;;
+      anytls) items+=("$(printf '{"id":"anytls","port":%s,"insecure":%s%s,"link":"%s"}' "$ANYTLS_PORT" "$insecure" "$pins" \
+        "anytls://$ANYTLS_PASSWORD@$ip:$ANYTLS_PORT?sni=$sni&$q_anytls#dsh-anytls")") ;;
+      ss) items+=("$(printf '{"id":"ss","port":%s,"method":"%s","link":"%s"}' "$SS_PORT" "$SS_METHOD" \
+        "ss://$(printf '%s:%s' "$SS_METHOD" "$SS_KEY" | b64url)@$ip:$SS_PORT#dsh-ss")") ;;
+    esac
+  done
+  local IFS=,
+  printf '{"server":"%s","cert":"%s","items":[%s]}' "$ip" "$CERT_MODE" "${items[*]}"
+}
+
+# {"mode":…} plus expiry for an issued IP certificate.
+cert_status_json() {
+  if [ "$CERT_MODE" != ip ] || ! uses_cert; then printf '{"mode":"%s"}' "$CERT_MODE"; return; fi
+  find_acme_cert
+  if [ -z "$ACME_CERT" ]; then printf '{"mode":"ip","issued":false}'; return; fi
+  local end secs
+  end=$(openssl x509 -enddate -noout -in "$ACME_CERT" | cut -d= -f2)
+  secs=$(( $(date -d "$end" +%s) - $(date +%s) ))
+  printf '{"mode":"ip","issued":true,"expires":"%s","expires_in_hours":%s}' "$(date -u -d "$end" +%FT%TZ)" "$((secs / 3600))"
+}
+
+load_state_or_fail() {
+  [ -f "$STATE_FILE" ] || fail not_installed "dsh-vpn is not installed"
+  # shellcheck disable=SC1090
+  . "$STATE_FILE"
+  PROTOCOLS=${PROTOCOLS:-reality,hy2}  # state written before protocol selection existed
+  CERT_MODE=${CERT_MODE:-self}
+}
+
+# ---------------------------------------------------------------- commands
+
+cmd_install() {
+  local sni="" regenerate=0 want_cert
+  PROTOCOLS=""; CERT_MODE=""; ACME_PROVIDER=""; CERT_FAILURE=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --protocols) validate_protocols "$2"; PROTOCOLS=$2; shift 2 ;;
+      --port)
+        [[ $2 =~ ^[a-z0-9]+=[0-9]+$ ]] || fail bad_args "bad --port value: $2"
+        PORT_OVERRIDES="$PORT_OVERRIDES $2"; shift 2 ;;
+      --sni) sni=$2; shift 2 ;;
+      --server) SERVER_OVERRIDE=$2; shift 2 ;;
+      --regenerate) regenerate=1; shift ;;
+      --cert)
+        case "$2" in self|ip) CERT_MODE=$2 ;; *) fail bad_args "bad --cert value: $2" ;; esac
+        shift 2 ;;
+      --acme-provider) ACME_PROVIDER=$2; shift 2 ;;
+      --cert-wait)  # seconds to wait for issuance before falling back (tests)
+        [[ $2 =~ ^[0-9]+$ ]] || fail bad_args "bad --cert-wait value: $2"
+        CERT_WAIT_SECONDS=$2; shift 2 ;;
+      *) fail bad_args "unknown option: $1" ;;
+    esac
+  done
+  require_root
+  require_systemd
+
+  # Validate the IP-certificate prerequisites before anything is written, so a
+  # refusal leaves the running node untouched.
+  want_cert=$CERT_MODE
+  if [ -z "$want_cert" ] && [ -f "$STATE_FILE" ]; then want_cert=$(sed -n 's/^CERT_MODE=//p' "$STATE_FILE"); fi
+  if [ "${want_cert:-self}" = ip ]; then
+    is_ip_literal "${SERVER_OVERRIDE:-}" \
+      || fail cert_needs_ip "IP certificates need the server's IP address as the node address (got: ${SERVER_OVERRIDE:-none})"
+    local blocker; blocker=$(port80_blocker)
+    [ -z "$blocker" ] || fail port80_in_use "TCP port 80 is already used by: $blocker"
+    NEW_CERT_IP=$SERVER_OVERRIDE
+  fi
+
+  install_deps
+  install_singbox
+  prepare_state "$regenerate" "$sni"
+  write_cert
+  write_config
+  write_unit
+  open_firewall
+  if [ "$CERT_MODE" = ip ] && uses_cert && ! wait_for_cert; then cert_fallback; fi
+  enable_bbr
+  resolve_ip
+  log "done"
+  local head='"ok":true'
+  [ -z "$CERT_FAILURE" ] || head="\"ok\":false,\"error\":\"cert_failed\",\"message\":\"$(json_escape "$CERT_FAILURE")\""
+  result "{$head,\"action\":\"install\",\"protocols\":\"$PROTOCOLS\",\"version\":\"$("$BIN" version | awk 'NR==1{print $3}')\",\"cert\":$(cert_status_json),\"links\":$(links_json)}"
+}
+
+cmd_status() {
+  require_root
+  local active=false version="" p t ok listening=()
+  [ -f "$STATE_FILE" ] || result '{"ok":true,"action":"status","installed":false}'
+  load_state_or_fail
+  systemctl is-active --quiet "$UNIT" && active=true
+  [ -x "$BIN" ] && version=$("$BIN" version | awk 'NR==1{print $3}')
+  for p in $ALL_PROTOCOLS; do
+    has_protocol "$p" || continue
+    ok=true
+    for t in $(protocol_transports "$p"); do
+      ss -Hln --"$t" | awk '{print $4}' | grep -Eq "[:.]$(protocol_port "$p")\$" || ok=false
+    done
+    listening+=("\"$p\":$ok")
+  done
+  local IFS=,
+  local cert; cert=$(cert_status_json)
+  result "{\"ok\":true,\"action\":\"status\",\"installed\":true,\"active\":$active,\"version\":\"$version\",\"protocols\":\"$PROTOCOLS\",\"cert\":$cert,\"listening\":{${listening[*]}}}"
+}
+
+cmd_links() {
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --server) SERVER_OVERRIDE=$2; shift 2 ;;
+      *) fail bad_args "unknown option: $1" ;;
+    esac
+  done
+  require_root
+  load_state_or_fail
+  resolve_ip
+  result "{\"ok\":true,\"action\":\"links\",\"protocols\":\"$PROTOCOLS\",\"links\":$(links_json)}"
+}
+
+cmd_uninstall() {
+  require_root
+  systemctl disable --now "$UNIT" >/dev/null 2>&1 || true
+  rm -f "$UNIT_FILE" /etc/sysctl.d/99-dsh-vpn.conf
+  systemctl daemon-reload 2>/dev/null || true
+  rm -rf "$STATE_DIR" "$BIN"
+  log "removed"
+  result '{"ok":true,"action":"uninstall"}'
+}
+
+main() {
+  local cmd=${1:-}; shift || true
+  case "$cmd" in
+    install) cmd_install "$@" ;;
+    status) cmd_status ;;
+    links) cmd_links "$@" ;;
+    uninstall) cmd_uninstall ;;
+    *) fail bad_args "usage: vpn.sh <install|status|links|uninstall>" ;;
+  esac
+}
+
+main "$@"