Telnet, SSH and Command-Line Control

// A Telnet server's view of the byte stream: commands start with IAC (255), data is everything else.
// Byte values from RFC 854 (commands), RFC 857 (ECHO), RFC 858 (SGA), RFC 1091 (TTYPE), RFC 1073 (NAWS).
const IAC = 255, DONT = 254, DO = 253, WONT = 252, WILL = 251, SB = 250, SE = 240;
const VERB = { 251: "WILL", 252: "WONT", 253: "DO", 254: "DONT" };
const OPT = { 1: "ECHO", 3: "SGA", 24: "TTYPE", 31: "NAWS" };
const hex = (bytes) => [...bytes].map((b) => b.toString(16).toUpperCase().padStart(2, "0")).join(" ");
const say = (bytes) => [...bytes].map((b, i) => (i === 0 ? "IAC" : VERB[b] ?? OPT[b] ?? b)).join(" ");

// Our policy: we will suppress go-ahead ourselves; we want the client's window size; nothing else.
const weWill = { 3: true }, weWant = { 31: true };
const ours = {}, theirs = {}, pending = {}; // option -> enabled? (both start false: plain NVT)
const send = (verb, opt) => { const b = [IAC, verb, opt]; console.log(`  server sends ${hex(b).padEnd(9)} ${say(b)}`); };

function negotiate(verb, opt) {
  const askingUs = verb === DO || verb === DONT;       // DO/DONT are about what WE do
  const state = askingUs ? ours : theirs;
  const wantOn = verb === DO || verb === WILL;
  if (pending[opt] === verb || pending[opt] + 1 === verb) {     // DO answers our WILL, DONT refuses it
    delete pending[opt]; state[opt] = wantOn;
    return console.log(`  ${VERB[verb]} ${OPT[opt]}: ${wantOn ? "accepts" : "refuses"} our offer, no reply`);
  }
  if (!!state[opt] === wantOn) return console.log(`  ${VERB[verb]} ${OPT[opt]}: already in that mode, no reply (RFC 854 loop rule)`);
  const allowed = wantOn && (askingUs ? weWill[opt] : weWant[opt]);
  state[opt] = !!allowed;
  send(askingUs ? (allowed ? WILL : WONT) : (allowed ? DO : DONT), opt);
}

let mode = "data", verb = 0, sub = [], text = "";
function feed(chunk) {
  for (const b of chunk) {
    if (mode === "data") b === IAC ? (mode = "iac") : (text += String.fromCharCode(b));
    else if (mode === "iac") {
      if (b === IAC) { text += "\xff"; mode = "data"; }          // IAC IAC = a literal 255 byte
      else if (VERB[b]) { verb = b; mode = "opt"; }
      else if (b === SB) { sub = []; mode = "sb"; }
      else mode = "data";                                       // NOP, GA, AYT...: ignored here
    } else if (mode === "opt") { negotiate(verb, b); mode = "data"; }
    else if (mode === "sb") b === IAC ? (mode = "sb-iac") : sub.push(b);
    else if (mode === "sb-iac") {
      if (b === SE) {
        const [opt, w1, w2, h1, h2] = sub;
        console.log(`  SB ${OPT[opt]} ... SE: window ${(w1 << 8) | w2} x ${(h1 << 8) | h2}`);
        mode = "data";
      } else { sub.push(b); mode = "sb"; }                       // IAC IAC inside SB = 255
    }
  }
}

console.log("connect:");
pending[3] = DO; send(WILL, 3);                                 // offer SGA; expect DO SGA back
const client = [
  [IAC, DO, 3, IAC, WILL],                                       // ack of SGA, then a command cut in half
  [31, IAC, WILL, 24, IAC, DO, 1],
  [IAC, SB, 31, 0, 80, 0],                                       // window-size subnegotiation, split
  [24, IAC, SE, ...Buffer.from("volume get\r\n")],
];
for (const chunk of client) { console.log(`chunk ${hex(chunk)}`); feed(chunk); }
console.log(`data for the command layer: ${JSON.stringify(text)}`);

connect:
  server sends FF FB 03  IAC WILL SGA
chunk FF FD 03 FF FB
  DO SGA: accepts our offer, no reply
chunk 1F FF FB 18 FF FD 01
  server sends FF FD 1F  IAC DO NAWS
  server sends FF FE 18  IAC DONT TTYPE
  server sends FF FC 01  IAC WONT ECHO
chunk FF FA 1F 00 50 00
chunk 18 FF F0 76 6F 6C 75 6D 65 20 67 65 74 0D 0A
  SB NAWS ... SE: window 80 x 24
data for the command layer: "volume get\r\n"

import net from "node:net";

const MAX_LINE = 200;                         // bytes; a device can't buffer forever
const device = { volume: 30, mute: false };   // shared by every session
let nextSession = 1;
const seen = [];                             // complete lines the server parsed, in order

const server = net.createServer((socket) => {
  const id = nextSession++;
  let pending = Buffer.alloc(0);              // bytes received but not yet a full line
  let skipping = false;                       // inside an over-long line: drop it up to its LF
  const reply = (text) => socket.write(`${text}\r\n`);
  reply(`hello, session ${id}`);

  socket.on("data", (chunk) => {
    pending = Buffer.concat([pending, chunk]);
    let nl;
    while ((nl = pending.indexOf(0x0a)) !== -1) {         // one command per LF
      const raw = pending.subarray(0, nl);
      pending = pending.subarray(nl + 1);
      if (skipping) { skipping = false; continue; }       // tail of a line we already refused
      if (raw.length > MAX_LINE) { reply("error: line too long"); continue; }
      const line = raw.toString("utf8").replace(/\r$/, "");
      seen.push(`s${id} ${JSON.stringify(line)}`);
      run(line);
    }
    if (!skipping && pending.length > MAX_LINE) {          // no LF in sight: refuse now, don't grow
      skipping = true;
      reply("error: line too long");
    }
    if (skipping) pending = Buffer.alloc(0);
  });

  function run(line) {
    const [verb, arg, value] = line.trim().split(/\s+/);
    if (verb === "volume" && arg === "get") reply(`volume ${device.volume}`);
    else if (verb === "volume" && arg === "set") { device.volume = Number(value); reply(`volume ${device.volume}`); }
    else if (verb === "mute" && arg === "get") reply(`mute ${device.mute ? "on" : "off"}`);
    else if (verb === "exit") { reply("bye"); socket.end(); }
    else reply(`error: unknown command: ${verb}`);
  }
  socket.on("error", () => {});                            // a reset client must not crash the device
});

// A test client: queues incoming lines so the script can await them one at a time.
function connect(port) {
  const socket = net.connect(port);
  const lines = [], waiting = [];
  let rest = "";
  socket.setEncoding("utf8");
  socket.on("data", (text) => {
    const parts = (rest + text).split("\r\n");
    rest = parts.pop();
    for (const l of parts) waiting.length ? waiting.shift()(l) : lines.push(l);
  });
  const next = () => (lines.length ? Promise.resolve(lines.shift()) : new Promise((r) => waiting.push(r)));
  const write = (s) => new Promise((r) => socket.write(s, r));
  return { next, write, closed: new Promise((r) => socket.on("close", r)) };
}
const pause = () => new Promise((r) => setTimeout(r, 15));

server.listen(0, "127.0.0.1", async () => {
  const { port } = server.address();
  const a = connect(port);
  console.log(`A: ${await a.next()}`);                     // greeted before B connects,
  const b = connect(port);                                 // so A is always session 1
  console.log(`B: ${await b.next()}`);

  // One command split over three writes, and two commands in one write.
  await a.write("vol"); await pause();
  await a.write("ume set 42\r\nmute g"); await pause();
  await a.write("et\r\n");
  console.log(`A: ${await a.next()}`);
  console.log(`A: ${await a.next()}`);

  await b.write("volume get\n");                           // bare LF works too
  console.log(`B: ${await b.next()}`);
  await b.write("x".repeat(300) + "\r\n");                 // longer than MAX_LINE
  console.log(`B: ${await b.next()}`);

  await a.write("exit\r\n"); console.log(`A: ${await a.next()}`);
  await b.write("exit\r\n"); console.log(`B: ${await b.next()}`);
  await Promise.all([a.closed, b.closed]);
  server.close(() => console.log(`server parsed, in order:\n  ${seen.join("\n  ")}`));
});

A: hello, session 1
B: hello, session 2
A: volume 42
A: mute off
B: volume 42
B: error: line too long
A: bye
B: bye
server parsed, in order:
  s1 "volume set 42"
  s1 "mute get"
  s2 "volume get"
  s1 "exit"
  s2 "exit"

// A small command grammar: verb, sub-verb, arguments; "double quotes" with \" and \\ escapes.
class CommandError extends Error {
  constructor(code, message) { super(message); this.code = code; }
}

function tokenize(line) {
  const tokens = [];
  let i = 0;
  while (i < line.length) {
    if (line[i] === " " || line[i] === "\t") { i++; continue; }
    let t = "";
    if (line[i] === '"') {
      for (i++; ; ) {
        if (i >= line.length) throw new CommandError("E_SYNTAX", "unterminated quote");
        const c = line[i++];
        if (c === '"') break;
        t += c === "\\" && i < line.length ? line[i++] : c;
      }
    } else while (i < line.length && !/[ \t"]/.test(line[i])) t += line[i++];
    tokens.push(t);
  }
  return tokens;
}
// Quote on the way out, so every response can be read back by the same tokenizer.
const quote = (s) => (/^[\w.:@-]+$/.test(s) ? s : `"${s.replace(/[\\"]/g, "\\$&")}"`);

const int = (name, lo, hi) => ({ hint: `<${name} ${lo}..${hi}>`, parse(s) {
  if (!/^\d+$/.test(s) || +s < lo || +s > hi) throw new CommandError("E_RANGE", `${name} must be ${lo}..${hi}, got ${quote(s)}`);
  return +s;
} });
const text = (name, max) => ({ hint: `"<${name}>"`, parse(s) {
  if (s.length > max) throw new CommandError("E_RANGE", `${name} is longer than ${max} characters`);
  return s;
} });

const state = { volume: 30, name: "Room 1", calls: 0 };
const commands = {
  volume: {
    get: { args: [], run: () => ["volume", state.volume] },
    set: { args: [int("level", 0, 50)], run: ([v]) => ["volume", (state.volume = v)] },
  },
  name: {
    get: { args: [], run: () => ["name", state.name] },
    set: { args: [text("name", 32)], run: ([v]) => ["name", (state.name = v)] },
  },
  call: { dial: { args: [text("address", 128)], run: ([to]) => ["call", ++state.calls, "dialing", to] } },
};
const usage = (verb) => Object.entries(commands[verb]).map(([sub, c]) => [verb, sub, ...c.args.map((a) => a.hint)].join(" ")).join(" | ");

function execute(line, format) {
  try {
    const [verb = "", sub = "", ...args] = tokenize(line);
    const v = verb.toLowerCase(), s = sub.toLowerCase();             // verbs are case-insensitive
    const group = Object.hasOwn(commands, v) && commands[v];        // not "constructor", "__proto__"
    if (!group) throw new CommandError("E_UNKNOWN", `unknown command ${quote(verb)}`);
    const cmd = Object.hasOwn(group, s) && group[s];
    if (!cmd || args.length !== cmd.args.length) throw new CommandError("E_USAGE", `usage: ${usage(v)}`);
    const result = cmd.run(cmd.args.map((a, k) => a.parse(args[k])));  // values keep their case
    return format === "json" ? JSON.stringify({ ok: true, result }) : result.map(String).map(quote).join(" ");
  } catch (e) {
    if (!(e instanceof CommandError)) throw e;
    return format === "json" ? JSON.stringify({ ok: false, code: e.code, message: e.message }) : `error: ${e.code} ${e.message}`;
  }
}

const session = [
  "volume set 42", "VOLUME GET", "volume set 70", "volume set loud", "volume",
  'name set "Board Room \\"East\\""', "name get", 'name set "Lobby', "reboot now", "constructor",
  "call dial sip:alice@example.com",
];
for (const line of session) console.log(`> ${line}\n< ${execute(line, "text")}`);
console.log("-- same commands, machine format --");
for (const line of ["volume get", "volume set 70"]) console.log(`> ${line}\n< ${execute(line, "json")}`);
console.log(`round trip: ${JSON.stringify(tokenize(execute("name get", "text")))}`);

> volume set 42
< volume 42
> VOLUME GET
< volume 42
> volume set 70
< error: E_RANGE level must be 0..50, got 70
> volume set loud
< error: E_RANGE level must be 0..50, got loud
> volume
< error: E_USAGE usage: volume get | volume set <level 0..50>
> name set "Board Room \"East\""
< name "Board Room \"East\""
> name get
< name "Board Room \"East\""
> name set "Lobby
< error: E_SYNTAX unterminated quote
> reboot now
< error: E_UNKNOWN unknown command reboot
> constructor
< error: E_UNKNOWN unknown command constructor
> call dial sip:alice@example.com
< call 1 dialing sip:alice@example.com
-- same commands, machine format --
> volume get
< {"ok":true,"result":["volume",42]}
> volume set 70
< {"ok":false,"code":"E_RANGE","message":"level must be 0..50, got 70"}
round trip: ["name","Board Room \"East\""]

import net from "node:net";
import { EventEmitter } from "node:events";

// The device: one call that moves connecting -> connected when the far end answers.
const device = new EventEmitter();
device.volume = 30;
device.dial = (to) => { device.call = { id: 1, to }; device.emit("callstatus", "connecting"); };
device.answer = () => device.emit("callstatus", "connected");

let live = 0;
const server = net.createServer((socket) => {
  live++;
  socket.setEncoding("utf8");                                     // decoder keeps split characters whole
  const subs = new Set();
  const send = (line) => socket.write(line + "\r\n");
  const onCall = (state) => send(`notification:callstatus:outgoing:${device.call.id}:${device.call.to}:${state}`);
  socket.on("close", () => {
    device.off("callstatus", onCall);                             // or every closed session leaks a listener
    if (--live === 0) server.close(() => console.log(`sessions closed, listeners left: ${device.listenerCount("callstatus")}`));
  });
  let rest = "";
  socket.on("data", (text) => {
    const lines = (rest + text).split("\r\n");
    rest = lines.pop();
    for (const line of lines) {
      const [verb, arg] = line.split(" ");
      if (verb === "notify" && subs.has(arg)) send(`info: already registered:${arg}`);
      else if (verb === "notify") { subs.add(arg); device.on("callstatus", onCall); send(`notify ${arg} success`); }
      else if (verb === "dial") { device.dial(arg); send(`dial ${arg} ok`); }   // event fires BEFORE the reply
      else if (verb === "volume") send(`volume ${device.volume}`);
      else if (verb === "mute") send("mute off");
    }
  });
});

// The transport both clients share: hands every line from the device to onLine.
function open(port, onLine) {
  const socket = net.connect(port);
  let rest = "";
  socket.setEncoding("utf8");
  socket.on("data", (t) => { const l = (rest + t).split("\r\n"); rest = l.pop(); l.forEach(onLine); });
  return socket;
}
// Naive: "the next line after my command is my answer".
function naiveClient(port) {
  const inbox = [], waiting = [];
  const socket = open(port, (l) => (waiting.length ? waiting.shift()(l) : inbox.push(l)));
  const next = () => (inbox.length ? Promise.resolve(inbox.shift()) : new Promise((r) => waiting.push(r)));
  return { socket, send: (cmd) => (socket.write(cmd + "\r\n"), next()) };
}
// Demultiplexing: notifications go to a handler; other lines answer the oldest command, in order.
function demuxClient(port, onNotification) {
  const pending = [];
  const socket = open(port, (l) => (l.startsWith("notification:") ? onNotification(l) : pending.shift()(l)));
  return { socket, send: (cmd) => new Promise((r) => { pending.push(r); socket.write(cmd + "\r\n"); }) };
}

server.listen(0, "127.0.0.1", async () => {
  const { port } = server.address();
  const seen = [];
  const naive = naiveClient(port);
  const smart = demuxClient(port, (n) => seen.push(n));
  const other = demuxClient(port, () => {});
  const show = async (who, c, cmd) => console.log(`${who.padEnd(6)} > ${cmd.padEnd(32)} < ${await c.send(cmd)}`);

  await show("naive", naive, "notify callstatus");
  await show("demux", smart, "notify callstatus");
  await show("demux", smart, "notify callstatus");
  await show("other", other, "dial sip:bob@example.com");      // another session starts a call
  device.answer();                                            // far end answers: a second event
  await show("naive", naive, "volume get");
  await show("naive", naive, "mute get");
  await show("demux", smart, "volume get");
  await show("demux", smart, "mute get");
  console.log(`demux client's notification handler got:\n  ${seen.join("\n  ")}`);
  for (const c of [naive, smart, other]) c.socket.end();
});

naive  > notify callstatus                < notify callstatus success
demux  > notify callstatus                < notify callstatus success
demux  > notify callstatus                < info: already registered:callstatus
other  > dial sip:bob@example.com         < dial sip:bob@example.com ok
naive  > volume get                       < notification:callstatus:outgoing:1:sip:bob@example.com:connecting
naive  > mute get                         < notification:callstatus:outgoing:1:sip:bob@example.com:connected
demux  > volume get                       < volume 30
demux  > mute get                         < mute off
demux client's notification handler got:
  notification:callstatus:outgoing:1:sip:bob@example.com:connecting
  notification:callstatus:outgoing:1:sip:bob@example.com:connected
sessions closed, listeners left: 0

import { generateKeyPairSync, createHash, timingSafeEqual } from "node:crypto";
import ssh2 from "ssh2";
const { Server, Client, utils } = ssh2;

// Keys made with node:crypto: P-256 in SEC1 PEM ("BEGIN EC PRIVATE KEY"), a format ssh2 reads.
const newKey = () => generateKeyPairSync("ec", { namedCurve: "prime256v1",
  privateKeyEncoding: { type: "sec1", format: "pem" }, publicKeyEncoding: { type: "spki", format: "pem" } }).privateKey;
const hostKey = newKey();          // the device's identity, made once at first boot
const adminKey = newKey();         // the admin's key; the device stores only its public half
const authorized = utils.parseKey(adminKey);
const fingerprint = (blob) => createHash("sha256").update(blob).digest("base64");
const pinned = fingerprint(utils.parseKey(hostKey).getPublicSSH());   // what the client trusts

const device = { volume: 30 };
function run(line) {                                   // stand-in for the shared command layer
  const [verb, sub, arg] = line.trim().split(/\s+/);
  if (verb === "volume" && sub === "get") return { out: `volume ${device.volume}` };
  if (verb === "volume" && sub === "set" && /^\d+$/.test(arg) && +arg <= 50) return { out: `volume ${(device.volume = +arg)}` };
  return { err: `error: E_USAGE ${line.trim()}`, code: 2 };
}

const server = new Server({ hostKeys: [hostKey] }, (client) => {
  client.on("authentication", (ctx) => {
    const keyOk = ctx.method === "publickey" && ctx.username === "admin" && ctx.key.algo === authorized.type
      && ctx.key.data.length === authorized.getPublicSSH().length && timingSafeEqual(ctx.key.data, authorized.getPublicSSH());
    if (!keyOk) return ctx.reject(["publickey"]);      // passwords are not offered at all
    if (!ctx.signature) return ctx.accept();           // "would you take this key?" probe
    authorized.verify(ctx.blob, ctx.signature, ctx.hashAlgo) === true ? ctx.accept() : ctx.reject();
  });
  client.on("ready", () => client.on("session", (accept) => {
    const session = accept();
    session.on("exec", (accept, reject, info) => {     // one command, an exit status, done
      const ch = accept();
      const r = run(info.command);
      r.out ? ch.write(r.out + "\n") : ch.stderr.write(r.err + "\n");
      ch.exit(r.code ?? 0);
      ch.end();
    });
    session.on("shell", (accept) => {                  // a long-lived, interactive session
      const ch = accept();
      let rest = "";
      ch.write("device> ");
      ch.on("data", (d) => {
        const lines = (rest + d).split("\n");
        rest = lines.pop();
        for (const line of lines) {
          if (line.trim() === "exit") { ch.write("bye\n"); ch.exit(0); return ch.end(); }
          const r = run(line);
          ch.write(`${r.out ?? r.err}\ndevice> `);
        }
      });
    });
  }));
  client.on("error", () => {});
});

const connect = (port, opts) => new Promise((resolve, reject) => {
  const c = new Client();
  c.on("ready", () => resolve(c)).on("error", reject);
  c.connect({ host: "127.0.0.1", port, username: "admin", ...opts });
});
const exec = (c, cmd) => new Promise((resolve) => {
  c.exec(cmd, (err, stream) => {
    let out = "", errText = "", code;
    stream.on("data", (d) => (out += d)).stderr.on("data", (d) => (errText += d));
    stream.on("exit", (c) => (code = c)).on("close", () => resolve({ out, errText, code }));
  });
});

server.listen(0, "127.0.0.1", async () => {
  const { port } = server.address();
  const trustPinned = (key) => fingerprint(key) === pinned;

  await connect(port, { password: "admin", hostVerifier: trustPinned })
    .catch((e) => console.log(`password login: ${e.message}`));
  await connect(port, { privateKey: adminKey, hostVerifier: () => false })
    .catch((e) => console.log(`unknown host key: ${e.message}`));

  const c = await connect(port, { privateKey: adminKey, hostVerifier: trustPinned });
  console.log("key login: ready (host key matched the pinned fingerprint)");
  for (const cmd of ["volume get", "volume set 70"]) {
    const r = await exec(c, cmd);
    console.log(`exec ${JSON.stringify(cmd)}: stdout=${JSON.stringify(r.out)} stderr=${JSON.stringify(r.errText)} exit=${r.code}`);
  }
  const transcript = await new Promise((resolve) => c.shell(false, (err, stream) => {
    let all = "";
    stream.on("data", (d) => (all += d)).on("close", () => resolve(all));
    stream.end("volume set 42\nvolume get\nexit\n");
  }));
  console.log(`shell transcript:\n${transcript}`);
  c.end();
  server.close();
});

password login: All configured authentication methods failed
unknown host key: Host denied (verification failed)
key login: ready (host key matched the pinned fingerprint)
exec "volume get": stdout="volume 30\n" stderr="" exit=0
exec "volume set 70": stdout="" stderr="error: E_USAGE volume set 70\n" exit=2
shell transcript:
device> volume 42
device> volume 42
device> bye

import express from "express";
import request from "supertest";
import net from "node:net";
import { generateKeyPairSync } from "node:crypto";
import ssh2 from "ssh2";
import { z } from "zod";

// ---- The command layer: one definition per operation, used by every transport ----
class CommandError extends Error {
  constructor(code, status, message) { super(message); Object.assign(this, { code, status }); }
}
const device = { volume: 30 };
const users = { "tok-admin": { name: "ana", role: "admin" }, "tok-view": { name: "raj", role: "viewer" } };
const RANK = { viewer: 1, admin: 2 };
const TITLE = { E_UNKNOWN: "Unknown command", E_FORBIDDEN: "Not allowed", E_INVALID: "Invalid argument" };
const audit = [];
const commands = {
  "volume.get": { role: "viewer", args: [], input: z.object({}), run: () => ({ level: device.volume }) },
  "volume.set": { role: "admin", args: ["level"], input: z.object({ level: z.number().int().min(0).max(50) }),
    run: ({ level }) => ({ level: (device.volume = level) }) },
};
function invoke(user, name, raw, via) {
  try {
    const cmd = Object.hasOwn(commands, name) ? commands[name] : null;
    if (!cmd) throw new CommandError("E_UNKNOWN", 404, `unknown command ${name}`);
    if (RANK[user.role] < RANK[cmd.role]) throw new CommandError("E_FORBIDDEN", 403, `${name} needs role ${cmd.role}`);
    const parsed = cmd.input.safeParse(raw);
    if (!parsed.success) {
      const i = parsed.error.issues[0];
      throw new CommandError("E_INVALID", 422, `${i.path.join(".")}: ${i.message}`);
    }
    const result = cmd.run(parsed.data);
    audit.push(`${via.padEnd(6)} ${user.name} ${name} ${JSON.stringify(raw)} -> ok`);
    return result;
  } catch (e) {
    audit.push(`${via.padEnd(6)} ${user.name} ${name} ${JSON.stringify(raw)} -> ${e.code}`);
    throw e;
  }
}

// ---- Adapter 1: REST (resource paths, JSON, problem details) ----
const app = express().use(express.json());
app.use((req, res, next) => (req.user = users[req.get("authorization")?.slice(7)]) ? next() : res.sendStatus(401));
app.get("/api/v1/audio/volume", (req, res) => res.json(invoke(req.user, "volume.get", {}, "rest")));
app.put("/api/v1/audio/volume", (req, res) => res.json(invoke(req.user, "volume.set", req.body, "rest")));
app.use((err, req, res, next) => res.status(err.status ?? 500).type("application/problem+json")
  .json({ type: `urn:device:error:${err.code}`, title: TITLE[err.code], status: err.status, detail: err.message }));

// ---- Adapter 2: lines ("volume set 42"), shared by Telnet and SSH ----
function runLine(user, line, via) {
  const [verb, sub, ...rest] = line.trim().split(/\s+/);
  const name = `${verb}.${sub}`;
  try {
    const keys = Object.hasOwn(commands, name) ? commands[name].args : [];
    const typed = rest.map((t) => (/^-?\d+$/.test(t) ? Number(t) : t));   // text -> JSON types, here only
    const result = invoke(user, name, Object.fromEntries(keys.map((k, i) => [k, typed[i]])), via);
    return { ok: true, text: `${verb} ${Object.values(result).join(" ")}` };
  } catch (e) {
    return { ok: false, text: `error: ${e.code} ${e.message}` };
  }
}
const telnet = net.createServer((sock) => {          // first line logs in, the rest are commands
  let user, rest = "";
  sock.setEncoding("utf8");
  sock.on("data", (d) => {
    const lines = (rest + d).split("\r\n");
    rest = lines.pop();
    for (const line of lines) {
      if (!user) { user = users[line.replace("login ", "")]; sock.write(user ? "ok\r\n" : "denied\r\n"); continue; }
      sock.write(runLine(user, line, "telnet").text + "\r\n");
    }
  });
});
const hostKey = generateKeyPairSync("ec", { namedCurve: "prime256v1", privateKeyEncoding: { type: "sec1", format: "pem" },
  publicKeyEncoding: { type: "spki", format: "pem" } }).privateKey;
const ssh = new ssh2.Server({ hostKeys: [hostKey] }, (client) => {   // password = token, to keep the model short
  let user;
  client.on("authentication", (ctx) => ((user = ctx.method === "password" && users[ctx.password]) ? ctx.accept() : ctx.reject(["password"])));
  client.on("ready", () => client.on("session", (accept) => accept().on("exec", (accept, reject, info) => {
    const ch = accept(), r = runLine(user, info.command, "ssh");
    (r.ok ? ch : ch.stderr).write(r.text + "\n");
    ch.exit(r.ok ? 0 : 1);
    ch.end();
  })));
});

// ---- The same operations through all three doors ----
const rest = async (token, level) => {
  const r = level === undefined ? await request(app).get("/api/v1/audio/volume").set("Authorization", `Bearer ${token}`)
    : await request(app).put("/api/v1/audio/volume").set("Authorization", `Bearer ${token}`).send({ level });
  return `${r.status} ${JSON.stringify(r.body)}`;
};
const telnetSession = (port, token, cmds) => new Promise((resolve) => {
  const s = net.connect(port), out = [];
  let buf = "";
  s.setEncoding("utf8");
  s.on("data", (d) => { buf += d; const l = buf.split("\r\n"); buf = l.pop(); out.push(...l); if (out.length === cmds.length + 1) s.end(); });
  s.on("close", () => resolve(out.slice(1)));
  s.write([`login ${token}`, ...cmds].map((c) => c + "\r\n").join(""));
});
const sshExec = (port, token, cmd) => new Promise((resolve) => {
  const c = new ssh2.Client();
  c.on("ready", () => c.exec(cmd, (err, st) => {
    let text = "", code;
    st.on("data", (d) => (text += d)).stderr.on("data", (d) => (text += d));
    st.on("exit", (x) => (code = x)).on("close", () => { c.end(); resolve(`exit ${code} ${text.trim()}`); });
  })).connect({ host: "127.0.0.1", port, username: "x", password: token, hostVerifier: () => true });
});

telnet.listen(0, "127.0.0.1", () => ssh.listen(0, "127.0.0.1", async () => {
  const tp = telnet.address().port, sp = ssh.address().port;
  console.log(`REST   PUT level 42 (ana)    ${await rest("tok-admin", 42)}`);
  console.log(`REST   PUT level 70 (ana)    ${await rest("tok-admin", 70)}`);
  const [t1, t2] = await telnetSession(tp, "tok-admin", ["volume set 70", "volume get"]);
  console.log(`Telnet volume set 70 (ana)   ${t1}\nTelnet volume get (ana)      ${t2}`);
  console.log(`SSH    volume set 70 (ana)   ${await sshExec(sp, "tok-admin", "volume set 70")}`);
  console.log(`SSH    volume set 10 (raj)   ${await sshExec(sp, "tok-view", "volume set 10")}`);
  console.log(`REST   PUT level 10 (raj)    ${await rest("tok-view", 10)}`);
  console.log(`REST   GET (raj)             ${await rest("tok-view")}`);
  console.log(`audit log, one format for every door:\n  ${audit.join("\n  ")}`);
  telnet.close();
  ssh.close();
}));