collabSupport/dect-relay-agent/README.md

DECT Relay Agent

Bridges the CollabSupport bot (public cloud) to Cisco DBS-210 DECT base stations on the private 10.0.0.0/8 corporate network.

Why it exists

The bot process runs in the public cloud and can't reach 10.x. This agent runs inside the data center, dials outbound over WSS to the bot, and executes any DECT command (collect status, reboot, factory-reset, etc.) the bot pushes to it.

Only one agent is expected to run at a time. If a second agent connects, the bot assumes it's a legitimate restart, closes the old socket, and adopts the new one.

Prerequisites

• Node.js ≥ 20
• Route from the agent host to 10.0.0.0/8 on TCP 443
• Route from the agent host to the bot's public HTTPS endpoint
• The DECT serviceability password (Control Hub → Calling → Features → DECT Networks → Manage → Manage DECT serviceability password)

Deploy paths

There are two ways to run this. Pick one based on where you're deploying.

1. Docker container in the data center (recommended for production)

Run the packager on your dev machine to produce a self-contained zip that includes the shared modules the agent imports:

# From the parent repo root:
npm run package:relay
# → writes dist/dect-relay-agent-bundle-<YYYYMMDD-HHMMSS>.zip

Transfer the zip to the DC host and follow the bundle's own README.md — three commands (unzip, edit .env, docker compose up -d --build).

If your DC host can't reach the npm registry, see the "No-internet DC option" section in the bundle's README — you can build the image on an internet-connected machine, docker save it to a tarball, and ship that instead.

2. Direct node process (dev + local iteration)

cd dect-relay-agent
npm install

ws, axios, and dotenv are the only runtime dependencies. The agent imports the shared integrations/cisco-dect/ modules from the parent repo via relative paths, so the parent workspace must be present on disk.

Configure

cp .env.example .env
$EDITOR .env

Required values:

Var	Meaning
DECT_RELAY_BOT_URL	Full WSS URL to the bot's DECT relay endpoint (wss://your-bot-host/dect-relay/ws)
DECT_RELAY_AGENT_TOKEN	Shared bearer token — MUST match the bot's DECT_RELAY_AGENT_TOKEN exactly
DECT_ADMIN_USER	Usually admin
DECT_ADMIN_PASSWORD	Fleet-wide serviceability password

Generate a fresh token: openssl rand -hex 32. Rotate on both sides at once — the bot compares tokens with timingSafeEqual and will reject any drift with a 401 on the WSS upgrade.

Run

npm start

You should see:

[startup] dect-relay-agent v0.1.0 — hostname=..., bot=wss://...
[connect] Dialing wss://.../dect-relay/ws
[connect] Connected — sending hello

And on the bot side:

[dect:relay-hub] Agent connected from ...
[dect:relay-hub] Agent hello: version=0.1.0 host=... caps=collect,reboot,...

Wire protocol

All frames are JSON, one per WebSocket message.

Agent → Bot on connect:

{ "type": "hello",
  "agentVersion": "0.1.0",
  "hostname": "dc-dect-relay-01",
  "capabilities": ["collect","reboot","force-reboot","reboot-chain",
                   "force-reboot-chain","factory-reset","reconfigure-tree"] }

Bot → Agent (command):

{ "id": "cmd_<uuid>", "type": "collect", "baseIp": "10.4.11.87" }
{ "id": "cmd_<uuid>", "type": "reboot",  "baseIp": "10.4.11.87" }

Agent → Bot (reply):

{ "id": "cmd_<uuid>", "ok": true, "elapsedMs": 812,
  "result": { "parsed": { ... }, "verdict": { "healthy": true, ... } } }

{ "id": "cmd_<uuid>", "ok": false,
  "error": { "code": "DIGEST_401", "message": "Base rejected credentials" } }

Heartbeat (both directions, every 30s):

{ "type": "ping", "at": 1720000000000 }
{ "type": "pong", "at": 1720000000000 }

The bot terminates the socket if no pong arrives within 90s; the agent auto-reconnects with exponential backoff (1s / 2s / 4s / … capped at 30s + 0-1000ms jitter).

Safety guarantees

• DECT admin credentials NEVER leave this agent. The bot only knows the WSS bearer token.
• All mutating actions (reboot, factory-reset, reconfigure-tree) are only executed when the bot explicitly issues the corresponding command frame. The agent has no autonomous logic.
• The agent enforces no policy — the bot decides who can reboot what. See the bot's audit log for the full record of actions taken (igmp:audit style scopes in daily log files).
• The agent quarantines mutating actions from probes via the exact same safety model as the CLI tool (integrations/cisco-dect/probes.js — GET-triggered actions are only reachable via explicit trigger* helpers, never via a generic path fetcher).

What's in this folder

File	Purpose
index.js	Agent entrypoint — WSS client + command dispatcher
package.json	Deps: ws, axios, dotenv
.env.example	Annotated env template
README.md	This file
Dockerfile	Multi-stage alpine build used by the deploy bundle
docker-compose.yml	One-command deploy on the DC host
.dockerignore	Defensive; the packager already excludes cruft

The Dockerfile is intentionally NOT designed to be built from this folder directly (docker build dect-relay-agent/ will fail — the shared modules live one level up and are outside the build context). Always build from a bundle produced by npm run package:relay, which assembles a workspace/ tree that makes the shared imports resolvable inside the build context.