collabSupport/dect-relay-agent

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)

Install

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).

Deploying as a container

A Dockerfile isn't included yet — production deployment shape is TBD. Minimum viable:

FROM node:20-alpine
WORKDIR /app
# The agent imports from ../integrations/cisco-dect/, so copy the
# whole workspace (or at least these two paths).
COPY package.json package-lock.json ./
COPY dect-relay-agent ./dect-relay-agent
COPY integrations/cisco-dect ./integrations/cisco-dect
COPY utils/httpDigestAuth.js ./utils/httpDigestAuth.js
RUN cd dect-relay-agent && npm ci --omit=dev
CMD ["node", "dect-relay-agent/index.js"]

Set the env vars from .env.example via your orchestrator's secret store, not baked into the image.