Node agent

The panel drives a node entirely over a signed HTTPS RPC channel (/rpc/*) that it proxies through its own server route, src/routes/api/public/node-rpc.ts — browsers cannot pin a self-signed certificate by fingerprint themselves, so the Node.js server does it on their behalf.

Browser (panel UI)
   -> Panel server route  /api/public/node-rpc         (Node.js https client)
      -> HTTPS + cert-pin + HMAC
      -> Node agent  /rpc/*  (FastAPI/uvicorn, self-signed TLS on AGENT_PORT)
         -> xray (systemd)     - VMess/VLESS/Trojan
         -> zivpn (systemd)    - UDP
         -> sshd               - SSH tunnels
         -> nginx              - front-end reverse proxy / TLS
         -> stunnel4           - SSH over TLS (445/447/777)

Node agent -> POST /api/public/node-handshake   (enrol / re-pin, once + periodic)
Node agent -> POST /api/public/node-heartbeat    (every ~3-5s / adaptive)
Node agent -> POST /api/public/node-ssh-usage    (SSH byte ledger, own channel)

A companion process, autoscript-node-ssh-ws (module agent.ssh_ws), bridges SSH over WebSocket in its own systemd unit at higher CPU priority than the agent, so telemetry never throttles real tunnel throughput.

File: node/agent/heartbeat.py (~1570 lines). Runs as an asyncio task alongside the RPC server and the SSH-usage loop (agent/main.py::_main).

The panel is the single source of truth for accounts. It pushes the full user set to a node either piggybacked on the heartbeat response (pull model, usersRev diffing avoids re-pushing unchanged sets), or directly via POST /rpc/users.apply (push model, used for immediate changes like "user was deleted"). Both paths converge on the same logic:

1. 1
   enforce.set_account_map(all_users) + enforce.apply_resets(all_users) — refresh username↔accountId map, honour panel-side quota resets.
2. 2
   enforce.filter_active() splits each protocol's user list into servable vs. blocked (expired / over-quota / panel forceBlock/status).
3. 3
   enforce.publish_gate() writes the connect-time admission gate (tmpfs marker files under /run/autoscript-node/gate/{managed,allow}/<login>) before any service reload, so a just-blocked user can never sneak a login in during the reload window. enforce.admit(name) is an O(1) stat()-based check a login hook calls.
4. 4
   xray.apply_users(), ssh_svc.apply_users(), zivpn_svc.apply_users() rewrite /usr/local/etc/xray/config.json, OS-level SSH accounts, and /etc/zivpn/config.json, reloading the affected service.
5. 5
   Accounts removed from the panel are removed from the OS/Xray config and their local quota/traffic ledger rows are wiped (enforce.reset_user, _purge_vpn_user).
6. 6
   system_policy.apply(policy, all_users) — ports / DNS / DoH block / torrent block / outbound routing for SSH+ZIVPN planes.
7. 7
   warp.apply(all_users, policy) — kernel-level WARP egress for SSH/ZIVPN accounts assigned a WARP outbound (Xray handles its own WARP internally).
8. 8
   limits.set_users(all_users) — refresh per-user IP-limit/speed-limit state.

All endpoints are POST /rpc/<name> unless noted, requireAuthorization: Bearer <BEARER> plus (X-Timestamp, X-Signature) when SHARED_SECRET is configured, and are proxied by the panel through POST /api/public/node-rpc {nodeId, host, port, method, payload, bearer?, timeoutMs?}.

• Per-method timeout table (METHOD_TIMEOUT_MS): most calls 5s default; net.speedtest 90s, net.probe 45s, agent.update/agent.update_safe/node.rebuild 300s, node.restart 120s, node.health 60s, backup.snapshot 120s, backup.restore_latest 180s, users.apply/users.push 90s, logs.purge/firewall.apply/system.tune 60s, xray.install 300s, xray.version 30s, agent.stop 30s, ping 3s.
• A circuit breaker trips after 2 consecutive failures on read-only status-style methods (ping, status, xray.version, net.probe, node.health) and fast-fails for 45s (BREAKER_COOLDOWN_MS) instead of opening a new TLS connection each poll — keeps the whole panel UI from freezing when a node is dead.
• Dials host (panelDomain/ip), falling back to fallbackHost then raw ip when DNS resolution fails.
• Keep-alive https.Agent pool, one per host:port, so repeat calls reuse an already pin-verified socket.

node/agent/services/enforce.py runs node-local, even while the panel is unreachable:

• Expiry — expiresAt (epoch ms or ISO), blocked once past.
• Quota — quotaGb (lifetime) and dailyQuotaGb (resets at local midnight). Ledger is keyed by the panel's stable accountId (fallback: username). Uses max(carry, local_total) — never sum() — against the panel's fleet-wide usedBytes to avoid double counting.
• Panel resets — usageResetAt/dailyResetAt watermarks let every node independently honour a reset exactly once.
• Fleet-wide verdicts — the panel computes suspension/disable across the whole fleet and ships it every heartbeat as forceBlock/status/_fleet_blocks; the node treats this as authoritative and cuts service immediately.
• Connect-time admission gate — tmpfs marker files at /run/autoscript-node/gate/managed/<login> and .../allow/<login>, refreshed only on diff. A login hook does two stat() calls to answer "may this login connect right now?" in microseconds. Login name = grvpn-<accountId> (or hashed suffix if too long) — never the recyclable username.
• note_blocked()/push_event() emit user.blocked/user.unblocked/user.quota.reset/user.removed/user.ledger.pruned node events, which ride the heartbeat's event queue and are also fired as outbound webhooks (Telegram/Discord) via agent/webhook.py.