wldx-admin-cli 0.0.0-stage → 1.1.0

package/src/commands/config.mjs

@@ -0,0 +1,280 @@
+// wx-admin config: the configuration of a PBX as files (one JSON per object), and the differences between a folder
+// and a PBX or between two PBX. Configuration as code: back up, keep in git, compare; nothing is written to a PBX.
+//
+// What is kept: dialplans (rules, included dialplans by name), the general dialplan settings, timetables, IVR menus,
+// switches, paging groups, queues (call groups), trunks (SIP, PSTN, FXO; passwords masked), trunk groups and ACL
+// groups. What is left out as it differs between PBX or changes by itself: ids, ACL dns, trunk registration status.
+import fs from 'node:fs';
+import path from 'node:path';
+import {UsageError} from 'wldx-core/errors';
+import {refuseUnsafeWrite} from 'wldx-core/files';
+import {oneLine, paint} from 'wldx-core/format';
+import {pbxClient} from '../pbx.mjs';
+import {maskSecrets} from './trunk.mjs';
+
+const listOf = (r) => (Array.isArray(r) ? r : (r?.records ?? []));
+
+// The kinds of objects: where to read them, their scope, and the name an object is known by.
+export const KINDS = {
+  dialplans: {
+    path: '/PBX/Dialplans/',
+    scope: 'dialplan',
+    name: (r) => r.name,
+    detail: (r) => `/PBX/Dialplans/${Number(r.id)}/`,
+  },
+  'dialplan-settings': {path: '/Dialplan/GeneralSettings/', scope: 'dialplan', single: true},
+  timetables: {path: '/Dialplan/timeTables/', scope: 'dialplan', name: (r) => r.title},
+  ivr: {path: '/Dialplan/Ivr/', scope: 'dialplan', name: (r) => r.title},
+  switches: {path: '/Dialplan/Switches/', scope: 'dialplan', name: (r) => r.title},
+  paging: {path: '/Dialplan/PagingGroups/', scope: 'dialplan', name: (r) => r.title},
+  queues: {path: '/Dialplan/CallGroups/', scope: 'callgroups', name: (r) => r.title},
+  'trunks-sip': {path: '/Trunks/Sip/', scope: 'trunks', name: (r) => r.title ?? r.name, mask: true},
+  'trunks-pstn': {path: '/Trunks/Pstn/', scope: 'trunks', name: (r) => r.title ?? r.name, mask: true},
+  'trunks-fxo': {path: '/Trunks/Fxo/', scope: 'trunks', name: (r) => r.title ?? r.username, mask: true},
+  'trunk-groups': {path: '/Trunks/Groups/', scope: 'trunks', name: (r) => r.name ?? r.title},
+  'acl-groups': {path: '/PBX/AclGroups/', scope: 'aclgroups', name: (r) => r.name},
+};
+const VOLATILE = new Set(['id', 'dn', 'status']);
+
+function kindsOf(only) {
+  if (!only) return Object.keys(KINDS);
+  const list = only
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const bad = list.filter((k) => !Object.hasOwn(KINDS, k));
+  if (bad.length) throw new UsageError(`Unknown kinds: ${bad.join(', ')}. Known: ${Object.keys(KINDS).join(', ')}`);
+  return list;
+}
+
+const strip = (o) => Object.fromEntries(Object.entries(o).filter(([k]) => !VOLATILE.has(k)));
+
+// The configuration of the PBX: {kind: {name: object}} (a single object under the name "settings").
+export async function snapshot(client, kinds, info = () => {}) {
+  const out = {};
+  for (const kind of kinds) {
+    const k = KINDS[kind];
+    let answer;
+    try {
+      answer = await client.call('GET', k.path, undefined, {scope: k.scope});
+    } catch (e) {
+      info(`${kind}: not read (${oneLine(e.message, 140)})`);
+      continue;
+    }
+    if (k.single) {
+      out[kind] = {settings: answer};
+      continue;
+    }
+    const records = listOf(answer);
+    const objects = {};
+    let dialplanNames;
+    if (kind === 'dialplans') dialplanNames = new Map(records.map((r) => [r.id, r.name]));
+    for (const r of records) {
+      let full = k.detail ? await client.call('GET', k.detail(r), undefined, {scope: k.scope}) : r;
+      if (kind === 'dialplans') {
+        // included dialplans by name (ids differ between PBX); negative ids are built-in and the same everywhere
+        full = {
+          ...full,
+          includedDialplans: (full.includedDialplans ?? []).map((x) =>
+            x.dialplanId > 0 && dialplanNames.has(x.dialplanId) ? {dialplan: dialplanNames.get(x.dialplanId)} : x,
+          ),
+        };
+      }
+      if (k.mask) full = maskSecrets(full);
+      let name = String(k.name(r) ?? r.id);
+      while (Object.hasOwn(objects, name)) name += '~';
+      objects[name] = strip(full);
+    }
+    out[kind] = objects;
+  }
+  return out;
+}
+
+const fileName = (name) =>
+  `${
+    String(name)
+      .replace(/[^A-Za-z0-9_.-]/g, '_')
+      .replace(/^\.+/, '_')
+      .slice(0, 120) || '_'
+  }.json`;
+
+// Each object as it is in its own file; manifest.json maps the files to the names the objects are known by.
+function writeBackup(dir, data, manifest) {
+  fs.mkdirSync(dir, {recursive: true});
+  if (fs.readdirSync(dir).length)
+    throw new UsageError(`${dir} is not empty: back up into a new or empty folder (nothing was overwritten)`);
+  const index = {};
+  for (const [kind, objects] of Object.entries(data)) {
+    const sub = path.join(dir, kind);
+    fs.mkdirSync(sub);
+    index[kind] = {};
+    for (const [name, obj] of Object.entries(objects)) {
+      let file = fileName(name);
+      while (Object.hasOwn(index[kind], file)) file = file.replace(/\.json$/, '_.json');
+      index[kind][file] = name;
+      fs.writeFileSync(path.join(sub, file), `${JSON.stringify(obj, null, 2)}\n`, {flag: 'wx'});
+    }
+  }
+  fs.writeFileSync(path.join(dir, 'manifest.json'), `${JSON.stringify({...manifest, objects: index}, null, 2)}\n`, {
+    flag: 'wx',
+  });
+}
+
+// A backup folder read back: {kind: {name: object}}.
+export function readBackup(dir, kinds) {
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(dir, 'manifest.json'), 'utf8'));
+  } catch {
+    throw new UsageError(`${dir} is not a backup of wx-admin config backup (no readable manifest.json)`);
+  }
+  const out = {};
+  for (const kind of kinds) {
+    const sub = path.join(dir, kind);
+    if (!fs.existsSync(sub)) continue;
+    const names = manifest.objects?.[kind] ?? {};
+    const objects = {};
+    for (const f of fs
+      .readdirSync(sub)
+      .filter((n) => n.endsWith('.json'))
+      .sort()) {
+      objects[Object.hasOwn(names, f) ? names[f] : f.slice(0, -5)] = JSON.parse(
+        fs.readFileSync(path.join(sub, f), 'utf8'),
+      );
+    }
+    out[kind] = objects;
+  }
+  return out;
+}
+
+// The paths where two JSON values differ: [{path, from, to}] (at most `max`).
+export function differences(a, b, at = '', out = [], max = 50) {
+  if (out.length >= max) return out;
+  const isObj = (v) => v && typeof v === 'object';
+  if (isObj(a) && isObj(b) && Array.isArray(a) === Array.isArray(b)) {
+    for (const k of new Set([...Object.keys(a), ...Object.keys(b)]))
+      differences(a[k], b[k], Array.isArray(a) ? `${at}[${k}]` : at ? `${at}.${k}` : k, out, max);
+  } else if (JSON.stringify(a) !== JSON.stringify(b)) out.push({path: at || '.', from: a, to: b});
+  return out;
+}
+
+// Only the kinds both sides have are compared (a kind one side could not read is `skipped`, not "all added").
+export function compare(left, right) {
+  const added = [];
+  const removed = [];
+  const changed = [];
+  const skipped = [...new Set([...Object.keys(left), ...Object.keys(right)])].filter(
+    (k) => !Object.hasOwn(left, k) || !Object.hasOwn(right, k),
+  );
+  const compared = Object.keys(left).filter((k) => Object.hasOwn(right, k));
+  for (const kind of compared) {
+    const l = left[kind] ?? {};
+    const r = right[kind] ?? {};
+    for (const name of Object.keys(r)) if (!Object.hasOwn(l, name)) added.push({kind, name});
+    for (const name of Object.keys(l)) if (!Object.hasOwn(r, name)) removed.push({kind, name});
+    for (const name of Object.keys(l)) {
+      if (!Object.hasOwn(r, name)) continue;
+      const paths = differences(l[name], r[name]);
+      if (paths.length) changed.push({kind, name, paths});
+    }
+  }
+  return {
+    same: compared.length > 0 && !added.length && !removed.length && !changed.length,
+    compared,
+    added,
+    removed,
+    changed,
+    skipped,
+  };
+}
+
+const short = (v) => (v === undefined ? '(none)' : oneLine(JSON.stringify(v), 60));
+
+export const groups = {
+  config: {
+    summary: 'the configuration as files: back up a PBX to a folder, compare a folder or another PBX with a PBX',
+    commands: {
+      backup: {
+        summary: 'write the configuration of the PBX to a new folder, one JSON file per object (passwords masked)',
+        usage: 'wx-admin config backup --to DIR [--only KIND,KIND…]',
+        details: `Kinds: ${Object.keys(KINDS).join(', ')}. A kind the access may not read is skipped with a note.`,
+        options: {
+          to: {type: 'string', placeholder: 'DIR', description: 'a new or empty folder'},
+          only: {type: 'string', placeholder: 'KINDS', description: 'only these kinds (comma-separated)'},
+        },
+        args: [0, 0],
+        async run(ctx) {
+          if (!ctx.values.to) throw new UsageError('--to is needed', ctx.usage());
+          const dir = path.resolve(ctx.cwd ?? process.cwd(), ctx.values.to);
+          refuseUnsafeWrite(path.join(dir, 'manifest.json'), ctx.env);
+          if (fs.existsSync(dir) && fs.readdirSync(dir).length)
+            throw new UsageError(
+              `${ctx.values.to} is not empty: back up into a new or empty folder (nothing was overwritten)`,
+            );
+          const kinds = kindsOf(ctx.values.only);
+          const client = await pbxClient(ctx);
+          const data = await snapshot(client, kinds, ctx.info);
+          const counts = Object.fromEntries(Object.entries(data).map(([k, v]) => [k, Object.keys(v).length]));
+          writeBackup(dir, data, {
+            pbx: client.target.host,
+            at: new Date(ctx.clock()).toISOString(),
+            tool: 'wx-admin config backup',
+            kinds: counts,
+          });
+          return {dir, pbx: client.target.host, kinds: counts};
+        },
+        text: (r) => [
+          `Backed up ${r.pbx} to ${r.dir}`,
+          ...Object.entries(r.kinds).map(([k, n]) => `  ${k.padEnd(18)} ${n}`),
+        ],
+      },
+      diff: {
+        summary: 'what differs between a backup folder (or another PBX) and the PBX',
+        usage: 'wx-admin config diff (<dir> | --with PBX) [--only KIND,KIND…]',
+        details: [
+          '+ is only on the PBX, - only in the folder (or the other PBX), ~ differs (the paths that do).',
+          'With --all-pbx, every PBX is compared with the same folder.',
+        ].join('\n'),
+        options: {
+          with: {
+            type: 'string',
+            placeholder: 'PBX',
+            description: 'compare with another PBX instead of a folder',
+            complete: 'pbxs',
+          },
+          only: {type: 'string', placeholder: 'KINDS', description: 'only these kinds (comma-separated)'},
+        },
+        args: [0, 1],
+        readOnly: true,
+        async run(ctx) {
+          if (!ctx.positionals[0] === !ctx.values.with)
+            throw new UsageError('Give a backup folder or --with PBX', ctx.usage());
+          const kinds = kindsOf(ctx.values.only);
+          const client = await pbxClient(ctx);
+          const left = ctx.values.with
+            ? await snapshot(await pbxClient({...ctx, pbx: ctx.values.with}), kinds, ctx.info)
+            : readBackup(path.resolve(ctx.cwd ?? process.cwd(), ctx.positionals[0]), kinds);
+          const right = await snapshot(client, kinds, ctx.info);
+          return {pbx: client.target.host, against: ctx.values.with ?? ctx.positionals[0], ...compare(left, right)};
+        },
+        text(r, ctx) {
+          const c = paint(ctx);
+          const skipped = r.skipped?.length
+            ? [c.dim(`not compared (not read on one side): ${r.skipped.join(', ')}`)]
+            : [];
+          if (!r.compared.length) return [`${r.pbx}: nothing to compare with ${r.against}`, ...skipped];
+          if (r.same) return [`${r.pbx}: no differences with ${r.against}`, ...skipped];
+          const lines = [`${r.pbx} compared with ${r.against}:`, ...skipped];
+          for (const x of r.added) lines.push(c.green(`+ ${x.kind}/${x.name}`));
+          for (const x of r.removed) lines.push(c.red(`- ${x.kind}/${x.name}`));
+          for (const x of r.changed) {
+            lines.push(c.yellow(`~ ${x.kind}/${x.name}`));
+            for (const p of x.paths.slice(0, 10)) lines.push(`    ${p.path}: ${short(p.from)} → ${short(p.to)}`);
+            if (x.paths.length > 10) lines.push(c.dim(`    … ${x.paths.length - 10} more`));
+          }
+          return lines;
+        },
+      },
+    },
+  },
+};

package/src/commands/device.mjs

@@ -0,0 +1,275 @@
+// wx-admin device: the devices (phones, W-AIR bases, Wizyconf…) of the PBX, over the PBX REST API.
+// Operations (OpenAPI tags Devices, Device), scope devices (the spec names none for PUT, DELETE, connect and
+// disconnect: devices:*):
+//   GET /Devices/                        the devices (count, start)
+//   POST /Devices/                       add devices by MAC {macs}
+//   PUT /Devices/{mac}/                  change {description, user, multipleUsers, settings: {dns, ntp, syslogServer…}}
+//   DELETE /Devices/{mac}/               delete
+//   POST /Devices/scan/                  look for devices in a range of addresses {range}
+//   GET /Devices/verify/                 check one device: ?address=&port= (the spec says a body with range and port;
+//                                        the PBX reads the query, and "address", not "range")
+//   POST|DELETE /Devices/{mac}/connect/  open or close the remote web access to a device
+//   POST /Device/ResetToken/             reset the token of a Wizyconf device {pin}
+// A MAC is given with or without separators (9C:75:14:02:8F:24, 9c7514028f24); the PBX takes 12 lower-case hex digits.
+// The token of a device (its password for provisioning) is never shown as text, and in JSON only with --show-secrets.
+import {readJsonInput as readJsonFile} from 'wldx-core/files';
+import {UsageError} from 'wldx-core/errors';
+import {oneLine, paint, table} from 'wldx-core/format';
+import {apiPath, query} from 'wldx-core/http';
+import {pbxClient} from '../pbx.mjs';
+
+const SCOPE = {scope: 'devices'};
+const HOST = /^[A-Za-z0-9]([A-Za-z0-9.-]{0,252})$|^[0-9a-fA-F:]+$/;
+const EXTENSION = /^[0-9A-Za-z*#+_-]{1,32}$/;
+
+// "9C:75:14:02:8F:24" → "9c7514028f24".
+export function normalizeMac(input) {
+  const mac = String(input ?? '')
+    .toLowerCase()
+    .replace(/[:.-]/g, '');
+  if (!/^[0-9a-f]{12}$/.test(mac)) throw new UsageError(`Not a MAC address: ${input}`);
+  return mac;
+}
+
+const showSecrets = {
+  'show-secrets': {type: 'boolean', description: 'with --output json: keep the device tokens (never shown as text)'},
+};
+
+// A device without its token, unless JSON with --show-secrets; tokenSet says whether it has one.
+function hideToken(d, ctx) {
+  if (!d || typeof d !== 'object' || (ctx.values['show-secrets'] && ctx.output === 'json')) return d;
+  const {token, ...rest} = d;
+  return 'token' in d ? {...rest, tokenSet: Boolean(token)} : rest;
+}
+
+async function readJsonInput(ctx, from) {
+  const data = await readJsonFile(ctx, from); // no credentials, nothing hidden in the home folder
+  return data;
+}
+
+const count = (v, name) => {
+  if (v === undefined) return undefined;
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 0) throw new UsageError(`--${name} is a whole number: ${v}`);
+  return n;
+};
+
+const checkHost = (v, name) => {
+  if (v !== '' && !HOST.test(v)) throw new UsageError(`--${name} is a host name or an IP address: ${v}`);
+  return v;
+};
+
+const users = (d) =>
+  [...new Set([d.user, ...(Array.isArray(d.multipleUsers) ? d.multipleUsers : [])].filter(Boolean))].join(',');
+
+const deviceRow = (d, c) => [
+  d.mac ?? '',
+  d.model ?? '',
+  users(d) || c.dim('no user'),
+  d.isOnline ? c.green('online') : c.dim('offline'),
+  d.address ?? '',
+  d.firmware ?? '',
+  oneLine(d.description ?? '', 40),
+];
+
+export const groups = {
+  device: {
+    summary: 'devices of the PBX: list, add, change, delete, scan the network, remote access, Wizyconf token',
+    commands: {
+      list: {
+        summary: 'the devices of the PBX: MAC, model, users, online, address, firmware',
+        usage: 'wx-admin device list [--count N] [--start N] [--show-secrets]',
+        options: {
+          count: {type: 'string', placeholder: 'N', description: 'at most this many devices'},
+          start: {type: 'string', placeholder: 'N', description: 'skip this many first'},
+          ...showSecrets,
+        },
+        args: [0, 0],
+        async run(ctx) {
+          const q = query({count: count(ctx.values.count, 'count'), start: count(ctx.values.start, 'start')});
+          const r = await (await pbxClient(ctx)).call('GET', `/Devices/${q}`, undefined, SCOPE);
+          return {...r, records: (r?.records ?? []).map((d) => hideToken(d, ctx))};
+        },
+        text: (r, ctx) => (r.records.length ? table(r.records.map((d) => deviceRow(d, paint(ctx)))) : 'No devices'),
+      },
+      add: {
+        summary: 'add devices by MAC address (they get their configuration from the PBX)',
+        usage: 'wx-admin device add <mac>...',
+        options: {},
+        args: [1, 100],
+        async run(ctx) {
+          const macs = ctx.positionals.map(normalizeMac);
+          return (await pbxClient(ctx)).call('POST', '/Devices/', {macs}, SCOPE);
+        },
+        text: (r) => {
+          const recs = r?.records ?? [];
+          if (!recs.length) return 'No devices added';
+          return ['Added:', ...table(recs.map((x) => [`  ${x.mac}`, x.value?.vendor ?? '', x.value?.model ?? '']))];
+        },
+      },
+      update: {
+        summary: 'change a device: description, user(s), DNS, NTP, syslog, or anything from a JSON file',
+        usage:
+          'wx-admin device update <mac> [--description TEXT] [--user EXT] [--users EXT,EXT] [--dns PRIMARY[,SECONDARY]] [--ntp HOST] [--timezone TZ] [--syslog HOST] [--from FILE|-]',
+        details: [
+          'Only what is given is sent. --from takes the fields of the API as JSON, e.g.',
+          '{"settings": {"voiceVLAN": {"voice": "on", "data": 10}, "useDst": true}}; the options win over it.',
+        ].join('\n'),
+        options: {
+          description: {type: 'string', placeholder: 'TEXT', description: 'the description of the device'},
+          user: {
+            type: 'string',
+            placeholder: 'EXT',
+            description: 'the extension of the user of the device (empty: none)',
+          },
+          users: {
+            type: 'string',
+            placeholder: 'EXT,EXT',
+            description: 'the extensions of the users of a device with several (W-AIR)',
+          },
+          dns: {type: 'string', placeholder: 'PRIMARY[,SECONDARY]', description: 'the DNS servers of the device'},
+          ntp: {type: 'string', placeholder: 'HOST', description: 'the time server of the device'},
+          timezone: {type: 'string', placeholder: 'TZ', description: 'the time zone of the device'},
+          syslog: {type: 'string', placeholder: 'HOST', description: 'the log server of the device'},
+          from: {type: 'string', placeholder: 'FILE', description: 'fields as JSON (a file, or - for stdin)'},
+        },
+        args: [1, 1],
+        async run(ctx) {
+          const v = ctx.values;
+          const mac = normalizeMac(ctx.positionals[0]);
+          const body = v.from ? await readJsonInput(ctx, v.from) : {};
+          if (!body || typeof body !== 'object' || Array.isArray(body)) throw new UsageError('--from is a JSON object');
+          delete body.token; // a token reset is device reset-token, not a field to send by accident
+          const settings = {...(body.settings ?? {})};
+          if (v.description !== undefined) body.description = v.description;
+          if (v.user !== undefined) {
+            if (v.user && !EXTENSION.test(v.user)) throw new UsageError(`Not an extension: ${v.user}`);
+            body.user = v.user;
+          }
+          if (v.users !== undefined) {
+            const list = v.users
+              .split(',')
+              .map((s) => s.trim())
+              .filter(Boolean);
+            for (const e of list) if (!EXTENSION.test(e)) throw new UsageError(`Not an extension: ${e}`);
+            body.multipleUsers = list;
+          }
+          if (v.dns !== undefined) {
+            const [primary, secondary] = v.dns.split(',').map((s) => checkHost(s.trim(), 'dns'));
+            settings.dns = {...(settings.dns ?? {}), primary, ...(secondary !== undefined ? {secondary} : {})};
+          }
+          if (v.ntp !== undefined || v.timezone !== undefined) {
+            settings.ntp = {
+              ...(settings.ntp ?? {}),
+              ...(v.ntp !== undefined ? {server: checkHost(v.ntp, 'ntp')} : {}),
+              ...(v.timezone !== undefined ? {timezone: v.timezone} : {}),
+            };
+          }
+          if (v.syslog !== undefined) settings.syslogServer = checkHost(v.syslog, 'syslog');
+          if (Object.keys(settings).length) body.settings = settings;
+          else delete body.settings;
+          if (!Object.keys(body).length) throw new UsageError('Nothing to change', ctx.usage());
+          const result = await (await pbxClient(ctx)).call('PUT', apiPath`/Devices/${mac}/`, body, SCOPE);
+          return {mac, changed: body, result};
+        },
+        text: (r) => `Updated the device ${r.mac}: ${Object.keys(r.changed).join(', ')}`,
+      },
+      delete: {
+        summary: 'delete a device from the PBX (needs --yes: it stops working with the PBX)',
+        usage: 'wx-admin device delete <mac> --yes',
+        options: {yes: {type: 'boolean', description: 'yes, delete it'}},
+        args: [1, 1],
+        async run(ctx) {
+          const mac = normalizeMac(ctx.positionals[0]);
+          if (!ctx.values.yes)
+            throw new UsageError('A deleted device stops working with the PBX: confirm with --yes', ctx.usage());
+          const result = await (await pbxClient(ctx)).call('DELETE', apiPath`/Devices/${mac}/`, undefined, SCOPE);
+          return {deleted: mac, result};
+        },
+        text: (r) => `Deleted the device ${r.deleted}`,
+      },
+      scan: {
+        summary: 'look for devices in a range of addresses of the network of the PBX',
+        usage: 'wx-admin device scan <range>',
+        details:
+          'A range as WMS takes it: 192.168.1.1-254, or one address. Then: wx-admin device verify <address> --port N.',
+        options: {},
+        args: [1, 1],
+        async run(ctx) {
+          const range = ctx.positionals[0];
+          if (!/^[0-9a-fA-F.:/-]{3,64}$/.test(range)) throw new UsageError(`Not a range of addresses: ${range}`);
+          return (await pbxClient(ctx)).call('POST', '/Devices/scan/', {range}, SCOPE);
+        },
+        text: (r) =>
+          r?.records?.length ? r.records.map((d) => `${d.address}${d.port ? `:${d.port}` : ''}`) : 'No devices found',
+      },
+      verify: {
+        summary: 'check a device at an address: its MAC, model, and whether the PBX may provision it',
+        usage: 'wx-admin device verify <address> [--port N]',
+        options: {port: {type: 'string', placeholder: 'N', description: 'the port of its web interface (default 80)'}},
+        args: [1, 1],
+        async run(ctx) {
+          const address = checkHost(ctx.positionals[0], 'address');
+          const port = Number(ctx.values.port ?? 80);
+          if (!Number.isInteger(port) || port < 1 || port > 65535)
+            throw new UsageError(`--port is a port (1-65535): ${ctx.values.port}`);
+          return (await pbxClient(ctx)).call('GET', `/Devices/verify/${query({address, port})}`, undefined, SCOPE);
+        },
+        text: (r) =>
+          `${r.address}:${r.port}  ${r.mac || 'no MAC'}  ${r.model || 'unknown model'}  ${r.allow ? 'can be provisioned' : 'cannot be provisioned'}`,
+      },
+      connect: {
+        summary: 'open the remote access to the web interface of a device, through the PBX',
+        usage: 'wx-admin device connect <mac>',
+        options: {},
+        args: [1, 1],
+        async run(ctx) {
+          const mac = normalizeMac(ctx.positionals[0]);
+          return {
+            mac,
+            ...((await (await pbxClient(ctx)).call('POST', apiPath`/Devices/${mac}/connect/`, undefined, SCOPE)) ?? {}),
+          };
+        },
+        text: (r) =>
+          `Connected to ${r.mac}${r.host ? ` (${r.host}${r.port ? `:${r.port}` : ''}${r.ssl ? ', TLS' : ''})` : ''}${r.opt ? `: ${r.opt}` : ''} — close it with wx-admin device disconnect ${r.mac} --yes`,
+      },
+      disconnect: {
+        summary: 'close the remote access to a device (needs --yes: whoever uses it loses it)',
+        usage: 'wx-admin device disconnect <mac> --yes',
+        options: {yes: {type: 'boolean', description: 'yes, close it'}},
+        args: [1, 1],
+        async run(ctx) {
+          const mac = normalizeMac(ctx.positionals[0]);
+          if (!ctx.values.yes)
+            throw new UsageError('Closing the remote access cuts whoever uses it: confirm with --yes', ctx.usage());
+          const result = await (await pbxClient(ctx)).call(
+            'DELETE',
+            apiPath`/Devices/${mac}/connect/`,
+            undefined,
+            SCOPE,
+          );
+          return {disconnected: mac, result};
+        },
+        text: (r) => `Closed the remote access to ${r.disconnected}`,
+      },
+      'reset-token': {
+        summary: 'reset the token of a Wizyconf device, by the PIN it shows, to provision it again (needs --yes)',
+        usage: 'wx-admin device reset-token <pin> --yes',
+        options: {yes: {type: 'boolean', description: 'yes, reset it'}},
+        args: [1, 1],
+        async run(ctx) {
+          const pin = ctx.positionals[0];
+          if (!/^\d{4,12}$/.test(pin)) throw new UsageError('The PIN is the digits the Wizyconf device shows');
+          if (!ctx.values.yes)
+            throw new UsageError(
+              'The device must be provisioned again after its token is reset: confirm with --yes',
+              ctx.usage(),
+            );
+          const result = await (await pbxClient(ctx)).call('POST', '/Device/ResetToken/', {pin}, SCOPE);
+          return {reset: true, result};
+        },
+        text: () => 'The token of the device was reset: provision it again',
+      },
+    },
+  },
+};