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)

## Install

```bash
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

```bash
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

```bash
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:**
```json
{ "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):**
```json
{ "id": "cmd_<uuid>", "type": "collect", "baseIp": "10.4.11.87" }
{ "id": "cmd_<uuid>", "type": "reboot",  "baseIp": "10.4.11.87" }
```

**Agent → Bot (reply):**
```json
{ "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):**
```json
{ "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:

```Dockerfile
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.