herdr-remote 0.2.26 → 0.2.28

package/README.md

@@ -29,10 +29,11 @@ through Windows Defender Firewall on private networks.
 
 ```bash
 herdr-remote start | stop | restart
+herdr-remote update [--json]  # Install the latest release and restart services
 herdr-remote status [--json]
 herdr-remote pair [--json]
 herdr-remote url
-herdr-remote admin-broker install | uninstall | status # Windows
+herdr-remote admin-broker install | uninstall | restart | status # Windows
 herdr-remote keepalive install | uninstall | restart | status
 herdr-remote plugin link | unlink | status
 herdr-remote --lang zh|en
@@ -40,10 +41,11 @@ herdr-remote --lang zh|en
 
 On Windows, the TUI's **Keep-alive** page can register a per-user Task Scheduler broker with highest
 privileges and start it for the signed-in account. Choose **Set up admin terminal access** and
-approve the one-time Windows prompt under the same account as Herdr Remote; paired WebUI windows
-can then open a standalone elevated PowerShell without another UAC prompt. The CLI
+approve the one-time Windows prompt under the same account as Herdr Remote; the WebUI's Admin
+button then opens an elevated PowerShell as a new Herdr tab without another UAC prompt. The CLI
 `admin-broker install` and `admin-broker uninstall` commands are also available for administrators.
-Use `admin-broker status` to check the broker.
+Use `admin-broker status` to check the broker. `herdr-remote update` restarts the broker on the new
+release unless an admin terminal is open; `admin-broker restart` does it later, without elevation.
 
 ## Herdr Plugin
 

package/README.zh-CN.md

@@ -29,16 +29,17 @@ Defender 防火墙提示中允许 `node.exe` 通过专用网络通信。
 
 ```bash
 herdr-remote start | stop | restart
+herdr-remote update [--json]  # 安装最新版本并重启服务
 herdr-remote status [--json]
 herdr-remote pair [--json]
 herdr-remote url
-herdr-remote admin-broker install | uninstall | status # Windows
+herdr-remote admin-broker install | uninstall | restart | status # Windows
 herdr-remote keepalive install | uninstall | restart | status
 herdr-remote plugin link | unlink | status
 herdr-remote --lang zh|en
 ```
 
-在 Windows 上，可在 TUI 的「保活」页面注册以当前账户最高权限运行的计划任务并启动 broker。选择「设置管理员终端」，使用运行 Herdr Remote 的同一账户批准一次 Windows 提权提示；之后，已配对的 WebUI 窗口可以新建独立的管理员 PowerShell，不再重复弹出 UAC。也可以使用 `admin-broker install` 和 `admin-broker uninstall` 命令管理任务，使用 `admin-broker status` 检查 broker。
+在 Windows 上，可在 TUI 的「保活」页面注册以当前账户最高权限运行的计划任务并启动 broker。选择「设置管理员终端」，使用运行 Herdr Remote 的同一账户批准一次 Windows 提权提示；之后，WebUI 的“管理员”按钮会在 Herdr 中新建一个管理员 PowerShell 标签页，不再重复弹出 UAC。也可以使用 `admin-broker install` 和 `admin-broker uninstall` 命令管理任务，使用 `admin-broker status` 检查 broker。`herdr-remote update` 会让 broker 以新版本重启（有管理员终端开着时除外），之后也可以用 `admin-broker restart` 重启，无需提权。
 
 ## Herdr 插件
 

package/dist/cli.js

@@ -26,7 +26,9 @@ Commands:
   pair [--json]        Create pairing code
   url                  Print browser access URL
   run [--daemon]       Run services in foreground (keep-alive)
-  admin-broker install | uninstall | status (Windows)
+  update [--json]      Install the latest release and restart services
+  admin-broker install | uninstall | restart | status (Windows)
+  admin-shell          Elevated PowerShell in this terminal (Windows)
   keepalive <action>   install | uninstall | restart | status
   plugin <action>      link | unlink | status  (Herdr plugin)
 
@@ -218,6 +220,18 @@ async function main(argv = process.argv.slice(2)) {
             process.stdout.write(`${resolvePublicUrl(config, preferredLanAddress())}\n`);
             return;
         }
+        case 'update': {
+            const { runUpdate } = await import('./update-command.js');
+            const outcome = await runUpdate(t, {
+                config,
+                ...(flags.json ? { report: () => { } } : {}),
+            });
+            if (flags.json)
+                printJson(outcome);
+            if (!outcome.ok)
+                process.exitCode = 1;
+            return;
+        }
         case 'run': {
             const { runForeground } = await import('./supervisor.js');
             await runForeground({ logToFiles: Boolean(flags.daemon) });
@@ -228,12 +242,18 @@ async function main(argv = process.argv.slice(2)) {
             const action = positional[1] || 'status';
             if (action === 'install') {
                 broker.installAdminBroker(t);
-                printJson({ installed: true, available: await broker.adminBrokerStatus() });
+                printJson({ installed: true, available: await broker.waitForAdminBroker() });
             }
             else if (action === 'uninstall') {
                 broker.uninstallAdminBroker(t);
                 printJson({ installed: false });
             }
+            else if (action === 'restart') {
+                if ((await broker.stopAdminBroker()) === 'busy')
+                    throw new Error(t('adminBroker.busy'));
+                broker.startAdminBrokerTask(t);
+                printJson({ available: await broker.waitForAdminBroker() });
+            }
             else if (action === 'status') {
                 printJson({ available: await broker.adminBrokerStatus() });
             }
@@ -242,6 +262,11 @@ async function main(argv = process.argv.slice(2)) {
             }
             return;
         }
+        case 'admin-shell': {
+            const { runAdminShell } = await import('./connector/admin-shell.js');
+            process.exitCode = await runAdminShell(t);
+            return;
+        }
         case 'keepalive': {
             const keepalive = await import('./keepalive/index.js');
             const action = positional[1] || 'status';

package/dist/connector/admin-broker.js

@@ -1,11 +1,17 @@
 import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { PtySession } from '../pty-session.js';
-import { PACKAGE_ROOT } from '../paths.js';
-import { ADMIN_BROKER_MAX_MESSAGE_BYTES, adminBrokerPipePath, adminBrokerTaskName, sendAdminBrokerMessage, } from './adminBrokerPipe.js';
+import { stateDir } from '../paths.js';
+import { ADMIN_BROKER_MAX_MESSAGE_BYTES, adminBrokerTaskName, adminBrokerTokenMatches, connectAdminBroker, listenAdminBroker, publishAdminBrokerEndpoint, sendAdminBrokerMessage, } from './adminBrokerEndpoint.js';
 const BROKER_PING_TIMEOUT_MS = 1_000;
+const BROKER_START_TIMEOUT_MS = 5_000;
+const BROKER_START_POLL_MS = 250;
+const BROKER_TASK_END_TIMEOUT_MS = 10_000;
+/** Time for a stopping broker's goodbye to reach the caller before the process ends. */
+const BROKER_EXIT_GRACE_MS = 1_000;
 function powershellQuote(value) {
     return `'${value.replaceAll("'", "''")}'`;
 }
@@ -26,18 +32,20 @@ function runPowerShell(script, t) {
         throw new Error(t('adminBroker.needsElevation'));
     }
 }
-export function installAdminBroker(t) {
-    if (process.platform !== 'win32')
-        throw new Error(t('adminBroker.windowsOnly'));
+/** Registers and starts the broker's logon task; run elevated. */
+export function adminBrokerTaskScript() {
     const brokerPath = fileURLToPath(import.meta.url);
-    const brokerCommand = `& ${powershellQuote(process.execPath)} ${powershellQuote(brokerPath)}`;
+    // Pinned so the broker publishes its endpoint where this install's callers look.
+    const brokerCommand = `$env:HERDR_REMOTE_STATE_DIR = ${powershellQuote(stateDir())}; & ${powershellQuote(process.execPath)} ${powershellQuote(brokerPath)}`;
     const encodedBrokerCommand = Buffer.from(brokerCommand, 'utf16le').toString('base64');
     const powershell = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
-    const script = `
+    // Not PACKAGE_ROOT: npm updates the package by renaming its directory, and
+    // Windows refuses while it is the working directory of this long-lived task.
+    return `
 $ErrorActionPreference = 'Stop'
 $taskName = ${powershellQuote(adminBrokerTaskName())}
 $user = [Security.Principal.WindowsIdentity]::GetCurrent().Name
-$action = New-ScheduledTaskAction -Execute ${powershellQuote(powershell)} -Argument ${powershellQuote(`-NoProfile -NonInteractive -WindowStyle Hidden -EncodedCommand ${encodedBrokerCommand}`)} -WorkingDirectory ${powershellQuote(PACKAGE_ROOT)}
+$action = New-ScheduledTaskAction -Execute ${powershellQuote(powershell)} -Argument ${powershellQuote(`-NoProfile -NonInteractive -WindowStyle Hidden -EncodedCommand ${encodedBrokerCommand}`)} -WorkingDirectory ${powershellQuote(stateDir())}
 $trigger = New-ScheduledTaskTrigger -AtLogOn -User $user
 $principal = New-ScheduledTaskPrincipal -UserId $user -LogonType Interactive -RunLevel Highest
 $settings = New-ScheduledTaskSettingsSet -MultipleInstances IgnoreNew -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Seconds 0)
@@ -45,7 +53,13 @@ Stop-ScheduledTask -TaskName $taskName -ErrorAction SilentlyContinue
 Register-ScheduledTask -TaskName $taskName -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Force | Out-Null
 Start-ScheduledTask -TaskName $taskName
 `;
-    runPowerShell(script, t);
+}
+export function installAdminBroker(t) {
+    if (process.platform !== 'win32')
+        throw new Error(t('adminBroker.windowsOnly'));
+    // The task cannot start in a working directory that does not exist yet.
+    fs.mkdirSync(stateDir(), { recursive: true });
+    runPowerShell(adminBrokerTaskScript(), t);
 }
 export function uninstallAdminBroker(t) {
     if (process.platform !== 'win32')
@@ -57,37 +71,85 @@ Stop-ScheduledTask -TaskName $taskName -ErrorAction SilentlyContinue
 Unregister-ScheduledTask -TaskName $taskName -Confirm:$false -ErrorAction SilentlyContinue
 `, t);
 }
-export function adminBrokerStatus() {
-    if (process.platform !== 'win32')
-        return Promise.resolve(false);
+/** Send the broker one request and read the type of its one reply, or null without one. */
+function requestAdminBroker(type) {
+    let broker;
+    try {
+        broker = connectAdminBroker();
+    }
+    catch {
+        return Promise.resolve(null);
+    }
+    const { socket, token } = broker;
     return new Promise((resolve) => {
         let settled = false;
         let response = '';
-        const socket = net.createConnection(adminBrokerPipePath());
-        const finish = (available) => {
+        const finish = (reply) => {
             if (settled)
                 return;
             settled = true;
             socket.destroy();
-            resolve(available);
+            resolve(reply);
         };
-        socket.setTimeout(BROKER_PING_TIMEOUT_MS, () => finish(false));
+        socket.setTimeout(BROKER_PING_TIMEOUT_MS, () => finish(null));
         socket.setEncoding('utf8');
-        socket.on('connect', () => sendAdminBrokerMessage(socket, { type: 'ping' }));
+        socket.on('connect', () => sendAdminBrokerMessage(socket, { type, token }));
         socket.on('data', (chunk) => {
             response += chunk;
-            if (response.includes('\n'))
-                finish(response.includes('"type":"pong"'));
+            const newline = response.indexOf('\n');
+            if (newline < 0)
+                return;
+            try {
+                finish(String(JSON.parse(response.slice(0, newline)).type));
+            }
+            catch {
+                finish(null);
+            }
         });
-        socket.on('error', () => finish(false));
+        socket.on('error', () => finish(null));
     });
 }
+export async function adminBrokerStatus() {
+    return (await requestAdminBroker('ping')) === 'pong';
+}
+/**
+ * Ask the broker to exit so its task can start it on a new release. It stays
+ * while an administrator terminal is open: that terminal may be the one asking.
+ * A broker from before this request answers neither way.
+ */
+export async function stopAdminBroker() {
+    const reply = await requestAdminBroker('shutdown');
+    return reply === 'bye' ? 'stopped' : reply === 'busy' ? 'busy' : 'unavailable';
+}
+/** Start the broker's task now, which the account that registered it may do unelevated. */
+export function startAdminBrokerTask(t) {
+    if (process.platform !== 'win32')
+        throw new Error(t('adminBroker.windowsOnly'));
+    runPowerShell(`
+$ErrorActionPreference = 'Stop'
+$taskName = ${powershellQuote(adminBrokerTaskName())}
+# A broker that was just stopped may still be ending, and IgnoreNew drops a start until it has.
+$deadline = [DateTime]::UtcNow.AddMilliseconds(${BROKER_TASK_END_TIMEOUT_MS})
+while ((Get-ScheduledTask -TaskName $taskName).State -eq 'Running' -and [DateTime]::UtcNow -lt $deadline) { Start-Sleep -Milliseconds ${BROKER_START_POLL_MS} }
+Start-ScheduledTask -TaskName $taskName
+`, t);
+}
+/** The task starts the broker a moment after it is registered; wait for it to answer. */
+export async function waitForAdminBroker() {
+    const deadline = Date.now() + BROKER_START_TIMEOUT_MS;
+    while (!(await adminBrokerStatus())) {
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, BROKER_START_POLL_MS));
+    }
+    return true;
+}
 function writeError(socket, error) {
     const message = error instanceof Error ? error.message : String(error);
     sendAdminBrokerMessage(socket, { type: 'error', message });
     socket.end();
 }
-function startBrokerPty(socket, message) {
+function startBrokerPty(socket, message, spawn) {
     if (typeof message.command !== 'string' || !message.command || message.command.length > 4096)
         throw new Error('Invalid administrator terminal command.');
     if (path.basename(message.command).toLowerCase() !== 'powershell.exe')
@@ -112,6 +174,7 @@ function startBrokerPty(socket, message) {
         platform: 'win32',
         // A plain PowerShell prompt does not need the Herdr UI's Kitty or mouse modes.
         fastWindowsPty: true,
+        spawn,
     });
     pty.start({
         cols: PtySession.clampDimension(message.cols, PtySession.DEFAULT_COLS),
@@ -132,9 +195,10 @@ function startBrokerPty(socket, message) {
     sendAdminBrokerMessage(socket, { type: 'started', pid: pty.terminal?.pid ?? 0 });
     return pty;
 }
-function runAdminBroker() {
-    if (process.platform !== 'win32')
-        throw new Error('Administrator PTYs are only supported on Windows.');
+/** Listen on loopback and publish the endpoint; every request must carry its token. */
+export function serveAdminBroker({ spawn, onShutdown = () => { }, } = {}) {
+    let token = '';
+    const sessions = new Set();
     const server = net.createServer((socket) => {
         socket.setEncoding('utf8');
         let pending = '';
@@ -162,17 +226,32 @@ function runAdminBroker() {
                 }
                 if (firstMessage) {
                     firstMessage = false;
+                    if (!adminBrokerTokenMatches(token, message.token)) {
+                        writeError(socket, new Error('Administrator terminal request was not authorized.'));
+                        return;
+                    }
                     if (message.type === 'ping') {
                         sendAdminBrokerMessage(socket, { type: 'pong' });
                         socket.end();
                         return;
                     }
+                    if (message.type === 'shutdown') {
+                        const busy = sessions.size > 0;
+                        sendAdminBrokerMessage(socket, { type: busy ? 'busy' : 'bye' });
+                        socket.end();
+                        if (!busy) {
+                            server.close();
+                            onShutdown();
+                        }
+                        return;
+                    }
                     if (message.type !== 'start') {
                         writeError(socket, new Error('Expected an administrator terminal start request.'));
                         return;
                     }
                     try {
-                        pty = startBrokerPty(socket, message);
+                        pty = startBrokerPty(socket, message, spawn);
+                        sessions.add(pty);
                     }
                     catch (error) {
                         writeError(socket, error);
@@ -196,11 +275,26 @@ function runAdminBroker() {
                 }
             }
         });
-        socket.on('close', () => pty?.kill());
-        socket.on('error', () => pty?.kill());
+        const release = () => {
+            if (!pty)
+                return;
+            pty.kill();
+            sessions.delete(pty);
+        };
+        socket.on('close', release);
+        socket.on('error', release);
     });
-    server.listen(adminBrokerPipePath());
-    server.on('error', (error) => {
+    listenAdminBroker(server, (port) => {
+        token = publishAdminBrokerEndpoint(port);
+    });
+    return server;
+}
+function runAdminBroker() {
+    if (process.platform !== 'win32')
+        throw new Error('Administrator PTYs are only supported on Windows.');
+    serveAdminBroker({
+        onShutdown: () => setTimeout(() => process.exit(0), BROKER_EXIT_GRACE_MS).unref(),
+    }).on('error', (error) => {
         process.stderr.write(`herdr-remote administrator broker: ${error.message}\n`);
     });
 }

package/dist/connector/admin-shell.js

@@ -0,0 +1,65 @@
+// `herdr-remote admin-shell`: the administrator terminal inside a Herdr tab.
+//
+// This process runs in the tab's pane with the pane's standard rights and
+// relays its console to an elevated PowerShell that the admin broker runs. On
+// Windows, Node's raw mode reads keys as VT input and writes VT output through
+// unchanged, so the relay is byte for byte.
+import { requestHerdr } from '../herdr-api.js';
+import { ADMIN_TAB_ENV } from './admin-tab.js';
+import { ElevatedPty } from './elevatedPty.js';
+const BROKER_UNAVAILABLE_CODES = ['ENOENT', 'ECONNREFUSED', 'ETIMEDOUT'];
+/** Close the pane this runs in, which closes the tab `openAdminTab` made for it. */
+async function closeOwnPane() {
+    const socketPath = process.env.HERDR_SOCKET_PATH;
+    const paneId = process.env.HERDR_PANE_ID;
+    if (process.env[ADMIN_TAB_ENV] !== '1' || !socketPath || !paneId)
+        return;
+    try {
+        await requestHerdr(socketPath, 'pane.close', { pane_id: paneId });
+    }
+    catch {
+        // The shell's prompt comes back instead; the user can close the tab.
+    }
+}
+export async function runAdminShell(t) {
+    const { stdin, stdout } = process;
+    if (process.platform !== 'win32')
+        throw new Error(t('adminBroker.windowsOnly'));
+    if (!stdin.isTTY || !stdout.isTTY)
+        throw new Error(t('adminShell.needsTerminal'));
+    const pty = new ElevatedPty({
+        command: 'powershell.exe',
+        args: ['-NoLogo', '-NoProfile'],
+        cwd: process.cwd(),
+    });
+    const relayInput = (data) => pty.write(data);
+    const relayResize = () => pty.resize(stdout.columns, stdout.rows);
+    stdin.setRawMode(true);
+    stdin.on('data', relayInput);
+    stdout.on('resize', relayResize);
+    try {
+        const exitCode = await new Promise((resolve, reject) => {
+            pty.start({
+                cols: stdout.columns,
+                rows: stdout.rows,
+                onData: (data) => stdout.write(data),
+                onExit: (event) => resolve(event.exitCode),
+                onError: reject,
+            });
+        });
+        await closeOwnPane();
+        return exitCode;
+    }
+    catch (error) {
+        const { code } = error;
+        if (code && BROKER_UNAVAILABLE_CODES.includes(code))
+            throw new Error(t('adminShell.brokerUnavailable'));
+        throw error;
+    }
+    finally {
+        stdin.off('data', relayInput);
+        stdout.off('resize', relayResize);
+        stdin.setRawMode(false);
+        stdin.pause();
+    }
+}

package/dist/connector/admin-tab.js

@@ -0,0 +1,90 @@
+// An administrator terminal as a tab of the workstation's own Herdr, opened at
+// a browser's request.
+//
+// Herdr's API cannot start a tab running a command of our choosing, so the tab
+// starts with the user's shell and `herdr-remote admin-shell` is typed into it
+// once that shell is running. Nor can the API focus a tab for one client:
+// `tab.focus` moves every client attached to this Herdr, which is the price of
+// the requesting window showing the new tab at once.
+import path from 'node:path';
+import { requestHerdr } from '../herdr-api.js';
+import { createTranslator, detectLocale } from '../i18n/index.js';
+import { cliEntryPoint } from '../keepalive/environment.js';
+import { adminBrokerStatus } from './admin-broker.js';
+const SHELL_START_TIMEOUT_MS = 5_000;
+const SHELL_START_POLL_MS = 100;
+/** Marks the tab's shell, so `admin-shell` knows it may close the pane when done. */
+export const ADMIN_TAB_ENV = 'HERDR_REMOTE_ADMIN_TAB';
+function powershellQuote(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function posixQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/** The command line that starts `admin-shell`, in the syntax of the tab's shell. */
+export function adminShellCommand(shell, node, entry) {
+    const name = path.win32
+        .basename(shell)
+        .toLowerCase()
+        .replace(/\.exe$/, '');
+    if (name === 'powershell' || name === 'pwsh') {
+        return `& ${powershellQuote(node)} ${powershellQuote(entry)} admin-shell`;
+    }
+    if (name === 'cmd')
+        return `"${node}" "${entry}" admin-shell`;
+    // Git Bash and other POSIX shells: forward slashes, or C:\ reads as escapes.
+    const posix = (file) => posixQuote(file.replaceAll('\\', '/'));
+    return `${posix(node)} ${posix(entry)} admin-shell`;
+}
+/** The new tab's shell, once Herdr reports it running. */
+async function waitForShell(request, socketPath, paneId) {
+    const deadline = Date.now() + SHELL_START_TIMEOUT_MS;
+    while (true) {
+        const info = await request(socketPath, 'pane.process_info', {
+            pane_id: paneId,
+        });
+        const shell = info.process_info?.foreground_processes?.[0]?.name;
+        if (shell)
+            return shell;
+        if (Date.now() >= deadline)
+            throw new Error('The new tab did not start a shell in time.');
+        await new Promise((resolve) => setTimeout(resolve, SHELL_START_POLL_MS));
+    }
+}
+export async function openAdminTab({ socketPath, label, request = requestHerdr, brokerReady = adminBrokerStatus, }) {
+    if (!(await brokerReady())) {
+        throw Object.assign(new Error('The administrator terminal broker is not running.'), {
+            code: 'admin_broker_unavailable',
+        });
+    }
+    const created = await request(socketPath, 'tab.create', {
+        label,
+        focus: false,
+        env: { [ADMIN_TAB_ENV]: '1' },
+    });
+    const paneId = created.root_pane.pane_id;
+    await request(socketPath, 'tab.focus', { tab_id: created.tab.tab_id });
+    const shell = await waitForShell(request, socketPath, paneId);
+    await request(socketPath, 'pane.send_input', {
+        pane_id: paneId,
+        text: adminShellCommand(shell, process.execPath, cliEntryPoint()),
+        keys: ['enter'],
+    });
+}
+/** Open the tab for a browser window, and tell that window when it could not. */
+export async function openAdminTabFor(streamId, options) {
+    const t = createTranslator(detectLocale({ preference: options.language }));
+    try {
+        await openAdminTab({ socketPath: options.socketPath, label: t('adminShell.tabLabel') });
+    }
+    catch (error) {
+        const { code, message } = error;
+        process.stderr.write(`herdr-remote host connector: could not open an admin tab: ${message}\n`);
+        options.send({
+            type: 'error',
+            clientId: streamId,
+            code: code === 'admin_broker_unavailable' ? code : 'admin_tab_failed',
+            message,
+        });
+    }
+}

package/dist/connector/adminBrokerEndpoint.js

@@ -0,0 +1,68 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { stateDir } from '../paths.js';
+const ADMIN_BROKER_TASK_NAME = 'HerdrRemoteAdminBroker';
+const ADMIN_BROKER_HOST = '127.0.0.1';
+export const ADMIN_BROKER_MAX_MESSAGE_BYTES = 2 * 1_024 * 1_024;
+function adminBrokerAccountId() {
+    const account = `${process.env.USERDOMAIN || ''}\\${process.env.USERNAME || process.env.USERPROFILE || 'default'}`;
+    return createHash('sha256').update(account.toLowerCase()).digest('hex').slice(0, 24);
+}
+export function adminBrokerTaskName() {
+    return `${ADMIN_BROKER_TASK_NAME}-${adminBrokerAccountId()}`;
+}
+// Not a named pipe: one created by an elevated process admits only
+// Administrators, so the connector's standard token gets EPERM, and opening it
+// to everyone would let any account add an instance of the same name and sit
+// in the middle. A loopback port cannot be taken over by another account, and
+// the token lives in the state directory, which only this account can read.
+function endpointPath() {
+    return path.join(stateDir(), 'admin-broker.json');
+}
+/** Record where the broker listens, with a fresh token callers must present. */
+export function publishAdminBrokerEndpoint(port) {
+    const token = randomBytes(32).toString('hex');
+    const file = endpointPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify({ port, token }), { mode: 0o600 });
+    fs.renameSync(temporary, file);
+    return token;
+}
+export function adminBrokerTokenMatches(expected, received) {
+    if (!expected || typeof received !== 'string')
+        return false;
+    const want = Buffer.from(expected);
+    const got = Buffer.from(received);
+    return want.length === got.length && timingSafeEqual(want, got);
+}
+function brokerUnavailable() {
+    return Object.assign(new Error('The administrator terminal broker is not running.'), {
+        code: 'ENOENT',
+    });
+}
+/** Connect to the running broker; the token goes in the first message. */
+export function connectAdminBroker() {
+    let endpoint;
+    try {
+        endpoint = JSON.parse(fs.readFileSync(endpointPath(), 'utf8'));
+    }
+    catch {
+        // Missing or half-written: either way no broker has published itself.
+        throw brokerUnavailable();
+    }
+    const { port, token } = endpoint;
+    if (!Number.isInteger(port) || typeof token !== 'string')
+        throw brokerUnavailable();
+    return { socket: net.createConnection({ host: ADMIN_BROKER_HOST, port: port }), token };
+}
+export function listenAdminBroker(server, onListening) {
+    server.listen(0, ADMIN_BROKER_HOST, () => {
+        onListening(server.address().port);
+    });
+}
+export function sendAdminBrokerMessage(socket, message) {
+    socket.write(`${JSON.stringify(message)}\n`);
+}