herdr-remote 0.2.25 → 0.2.27

package/README.md

@@ -32,11 +32,19 @@ herdr-remote start | stop | restart
 herdr-remote status [--json]
 herdr-remote pair [--json]
 herdr-remote url
+herdr-remote admin-broker install | uninstall | status # Windows
 herdr-remote keepalive install | uninstall | restart | status
 herdr-remote plugin link | unlink | status
 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; 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.
+
 ## Herdr Plugin
 
 Register as a native Herdr plugin:

package/README.zh-CN.md

@@ -32,11 +32,14 @@ herdr-remote start | stop | restart
 herdr-remote status [--json]
 herdr-remote pair [--json]
 herdr-remote url
+herdr-remote admin-broker install | uninstall | 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 的“管理员”按钮会在 Herdr 中新建一个管理员 PowerShell 标签页，不再重复弹出 UAC。也可以使用 `admin-broker install` 和 `admin-broker uninstall` 命令管理任务，使用 `admin-broker status` 检查 broker。
+
 ## Herdr 插件
 
 注册为 Herdr 插件：

package/dist/cli.js

@@ -26,6 +26,8 @@ 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)
+  admin-shell          Elevated PowerShell in this terminal (Windows)
   keepalive <action>   install | uninstall | restart | status
   plugin <action>      link | unlink | status  (Herdr plugin)
 
@@ -222,6 +224,30 @@ async function main(argv = process.argv.slice(2)) {
             await runForeground({ logToFiles: Boolean(flags.daemon) });
             return;
         }
+        case 'admin-broker': {
+            const broker = await import('./connector/admin-broker.js');
+            const action = positional[1] || 'status';
+            if (action === 'install') {
+                broker.installAdminBroker(t);
+                printJson({ installed: true, available: await broker.waitForAdminBroker() });
+            }
+            else if (action === 'uninstall') {
+                broker.uninstallAdminBroker(t);
+                printJson({ installed: false });
+            }
+            else if (action === 'status') {
+                printJson({ available: await broker.adminBrokerStatus() });
+            }
+            else {
+                throw new Error(`unknown administrator broker action: ${action}`);
+            }
+            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-setup.js

@@ -0,0 +1,40 @@
+import { spawn } from 'node:child_process';
+import { cliEntryPoint } from '../keepalive/environment.js';
+import { encodePowerShellCommand, escapePowerShellSingleQuoted, } from '../keepalive/windows-service.js';
+function waitForChild(child) {
+    return new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (code) => resolve(code ?? 1));
+    });
+}
+export function renderAdminBrokerElevationScript({ action, nodePath, entryPoint, }) {
+    const quote = escapePowerShellSingleQuoted;
+    const args = `"${entryPoint}" admin-broker ${action} --elevated`;
+    return `$ErrorActionPreference = 'Stop'
+try {
+  $process = Start-Process -FilePath '${quote(nodePath)}' -ArgumentList '${quote(args)}' -Verb RunAs -Wait -PassThru -WindowStyle Hidden
+} catch {
+  if (($_.Exception.HResult -band 65535) -eq 1223) { exit 1223 }
+  exit 1
+}
+exit $process.ExitCode`;
+}
+function elevatedErrorCode(message, code) {
+    return Object.assign(new Error(message), { code });
+}
+/** Register the per-user task from the Windows TUI, requesting elevation once. */
+export async function configureAdminBroker(action, t) {
+    if (process.platform !== 'win32')
+        throw new Error(t('adminBroker.windowsOnly'));
+    const script = renderAdminBrokerElevationScript({
+        action,
+        nodePath: process.execPath,
+        entryPoint: cliEntryPoint(),
+    });
+    const child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', encodePowerShellCommand(script)], { windowsHide: true, stdio: 'ignore' });
+    const exitCode = await waitForChild(child);
+    if (exitCode === 1223)
+        throw elevatedErrorCode(t('adminBroker.elevationCancelled'), 'ELEVATION_CANCELLED');
+    if (exitCode !== 0)
+        throw new Error(t('adminBroker.setupFailed'));
+}

package/dist/connector/admin-broker.js

@@ -0,0 +1,237 @@
+import { execFileSync } from 'node:child_process';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PtySession } from '../pty-session.js';
+import { PACKAGE_ROOT, 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;
+function powershellQuote(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function runPowerShell(script, t) {
+    try {
+        execFileSync('powershell.exe', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-EncodedCommand',
+            Buffer.from(script, 'utf16le').toString('base64'),
+        ], {
+            stdio: 'pipe',
+            windowsHide: true,
+            timeout: 15_000,
+        });
+    }
+    catch {
+        throw new Error(t('adminBroker.needsElevation'));
+    }
+}
+export function installAdminBroker(t) {
+    if (process.platform !== 'win32')
+        throw new Error(t('adminBroker.windowsOnly'));
+    const brokerPath = fileURLToPath(import.meta.url);
+    // 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 = `
+$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)}
+$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)
+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 uninstallAdminBroker(t) {
+    if (process.platform !== 'win32')
+        throw new Error(t('adminBroker.windowsOnly'));
+    runPowerShell(`
+$ErrorActionPreference = 'Stop'
+$taskName = ${powershellQuote(adminBrokerTaskName())}
+Stop-ScheduledTask -TaskName $taskName -ErrorAction SilentlyContinue
+Unregister-ScheduledTask -TaskName $taskName -Confirm:$false -ErrorAction SilentlyContinue
+`, t);
+}
+export function adminBrokerStatus() {
+    let broker;
+    try {
+        broker = connectAdminBroker();
+    }
+    catch {
+        return Promise.resolve(false);
+    }
+    const { socket, token } = broker;
+    return new Promise((resolve) => {
+        let settled = false;
+        let response = '';
+        const finish = (available) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(available);
+        };
+        socket.setTimeout(BROKER_PING_TIMEOUT_MS, () => finish(false));
+        socket.setEncoding('utf8');
+        socket.on('connect', () => sendAdminBrokerMessage(socket, { type: 'ping', token }));
+        socket.on('data', (chunk) => {
+            response += chunk;
+            if (response.includes('\n'))
+                finish(response.includes('"type":"pong"'));
+        });
+        socket.on('error', () => finish(false));
+    });
+}
+/** 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) {
+    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')
+        throw new Error('The administrator broker only starts PowerShell.');
+    if (!Array.isArray(message.args) ||
+        message.args.length > 128 ||
+        !message.args.every((arg) => typeof arg === 'string'))
+        throw new Error('Invalid administrator terminal arguments.');
+    if (message.args.length !== 2 ||
+        message.args[0] !== '-NoLogo' ||
+        message.args[1] !== '-NoProfile')
+        throw new Error('The administrator broker only starts an interactive PowerShell prompt.');
+    if (typeof message.cwd !== 'string' || message.cwd.length > 4096)
+        throw new Error('Invalid administrator terminal working directory.');
+    if (message.socketPath !== null && message.socketPath !== undefined)
+        throw new Error('An administrator PowerShell session does not use a Herdr socket.');
+    const pty = new PtySession({
+        command: message.command,
+        args: message.args,
+        cwd: message.cwd,
+        socketPath: message.socketPath,
+        platform: 'win32',
+        // A plain PowerShell prompt does not need the Herdr UI's Kitty or mouse modes.
+        fastWindowsPty: true,
+    });
+    pty.start({
+        cols: PtySession.clampDimension(message.cols, PtySession.DEFAULT_COLS),
+        rows: PtySession.clampDimension(message.rows, PtySession.DEFAULT_ROWS),
+        onData: (data) => {
+            if (socket.writable)
+                sendAdminBrokerMessage(socket, {
+                    type: 'data',
+                    dataBase64: Buffer.from(data).toString('base64'),
+                });
+        },
+        onExit: ({ exitCode, signal }) => {
+            if (socket.writable)
+                sendAdminBrokerMessage(socket, { type: 'exit', exitCode, signal });
+            socket.end();
+        },
+    });
+    sendAdminBrokerMessage(socket, { type: 'started', pid: pty.terminal?.pid ?? 0 });
+    return pty;
+}
+/** Listen on loopback and publish the endpoint; every request must carry its token. */
+export function serveAdminBroker() {
+    let token = '';
+    const server = net.createServer((socket) => {
+        socket.setEncoding('utf8');
+        let pending = '';
+        let pty = null;
+        let firstMessage = true;
+        socket.on('data', (chunk) => {
+            pending += chunk;
+            if (Buffer.byteLength(pending, 'utf8') > ADMIN_BROKER_MAX_MESSAGE_BYTES) {
+                socket.destroy(new Error('Administrator terminal message exceeded the limit.'));
+                return;
+            }
+            while (true) {
+                const newline = pending.indexOf('\n');
+                if (newline < 0)
+                    return;
+                const line = pending.slice(0, newline);
+                pending = pending.slice(newline + 1);
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    writeError(socket, new Error('Invalid administrator terminal message.'));
+                    return;
+                }
+                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 !== 'start') {
+                        writeError(socket, new Error('Expected an administrator terminal start request.'));
+                        return;
+                    }
+                    try {
+                        pty = startBrokerPty(socket, message);
+                    }
+                    catch (error) {
+                        writeError(socket, error);
+                        return;
+                    }
+                    continue;
+                }
+                if (!pty)
+                    return;
+                if (message.type === 'input' && typeof message.dataBase64 === 'string') {
+                    if (message.dataBase64.length <= ADMIN_BROKER_MAX_MESSAGE_BYTES)
+                        pty.write(Buffer.from(message.dataBase64, 'base64'));
+                }
+                else if (message.type === 'resize') {
+                    pty.resize(message.cols, message.rows);
+                }
+                else if (message.type === 'kill') {
+                    pty.kill();
+                    socket.end();
+                    return;
+                }
+            }
+        });
+        socket.on('close', () => pty?.kill());
+        socket.on('error', () => pty?.kill());
+    });
+    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().on('error', (error) => {
+        process.stderr.write(`herdr-remote administrator broker: ${error.message}\n`);
+    });
+}
+if (path.basename(process.argv[1] || '') === 'admin-broker.js')
+    runAdminBroker();

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`);
+}

package/dist/connector/elevatedPty.js

@@ -0,0 +1,141 @@
+import { ADMIN_BROKER_MAX_MESSAGE_BYTES, connectAdminBroker, sendAdminBrokerMessage, } from './adminBrokerEndpoint.js';
+const BROKER_CONNECT_TIMEOUT_MS = 5_000;
+/** A PTY the admin broker runs elevated, driven over its loopback socket. */
+export class ElevatedPty {
+    socket = null;
+    input = '';
+    connected = false;
+    started = false;
+    finished = false;
+    killed = false;
+    /** Keystrokes typed while the elevated shell was still starting. */
+    early = [];
+    dataListener = null;
+    exitListener = null;
+    errorListener = null;
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    start({ cols, rows, onData, onExit, onError }) {
+        this.dataListener = onData;
+        this.exitListener = onExit;
+        this.errorListener = onError;
+        let broker;
+        try {
+            broker = connectAdminBroker();
+        }
+        catch (error) {
+            this.fail(error);
+            return;
+        }
+        const { socket, token } = broker;
+        this.socket = socket;
+        socket.setEncoding('utf8');
+        socket.setTimeout(BROKER_CONNECT_TIMEOUT_MS, () => {
+            socket.destroy(Object.assign(new Error('Administrator terminal broker connection timed out'), {
+                code: 'ETIMEDOUT',
+            }));
+        });
+        socket.on('connect', () => {
+            this.connected = true;
+            socket.setTimeout(0);
+            sendAdminBrokerMessage(socket, { type: 'start', token, ...this.options, cols, rows });
+        });
+        socket.on('data', (chunk) => this.receive(chunk));
+        socket.on('error', (error) => this.fail(error));
+        socket.on('close', () => {
+            if (this.started && !this.finished && !this.killed) {
+                this.finished = true;
+                this.exitListener?.({ exitCode: 1 });
+            }
+        });
+    }
+    write(data) {
+        if (this.finished)
+            return;
+        if (!this.started) {
+            this.early.push(Buffer.from(data));
+            return;
+        }
+        if (this.socket?.writable) {
+            sendAdminBrokerMessage(this.socket, {
+                type: 'input',
+                dataBase64: Buffer.from(data).toString('base64'),
+            });
+        }
+    }
+    resize(cols, rows) {
+        if (this.started && this.socket?.writable) {
+            sendAdminBrokerMessage(this.socket, { type: 'resize', cols, rows });
+        }
+    }
+    kill() {
+        this.killed = true;
+        if (!this.socket)
+            return;
+        if (this.connected && this.socket.writable) {
+            sendAdminBrokerMessage(this.socket, { type: 'kill' });
+            this.socket.end();
+        }
+        else {
+            this.socket.destroy();
+        }
+    }
+    receive(chunk) {
+        this.input += chunk;
+        if (Buffer.byteLength(this.input, 'utf8') > ADMIN_BROKER_MAX_MESSAGE_BYTES) {
+            this.socket?.destroy(new Error('Administrator terminal broker message exceeded the limit'));
+            return;
+        }
+        while (true) {
+            const newline = this.input.indexOf('\n');
+            if (newline < 0)
+                return;
+            const line = this.input.slice(0, newline);
+            this.input = this.input.slice(newline + 1);
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                this.socket?.destroy(new Error('Administrator terminal broker sent invalid JSON'));
+                return;
+            }
+            if (message.type === 'started') {
+                this.started = true;
+                const early = Buffer.concat(this.early);
+                this.early = [];
+                if (early.length > 0)
+                    this.write(early);
+            }
+            else if (message.type === 'data' && typeof message.dataBase64 === 'string') {
+                this.dataListener?.(Buffer.from(message.dataBase64, 'base64').toString('utf8'));
+            }
+            else if (message.type === 'exit') {
+                this.finished = true;
+                this.exitListener?.({
+                    exitCode: Number(message.exitCode) || 0,
+                    ...(typeof message.signal === 'number' ? { signal: message.signal } : {}),
+                });
+                this.socket?.end();
+            }
+            else if (message.type === 'error') {
+                this.fail(new Error(typeof message.message === 'string' ? message.message : 'Admin PTY failed'));
+            }
+        }
+    }
+    fail(error) {
+        if (this.started) {
+            if (!this.finished && !this.killed) {
+                this.finished = true;
+                this.exitListener?.({ exitCode: 1 });
+            }
+            return;
+        }
+        if (this.finished || this.killed)
+            return;
+        this.finished = true;
+        this.errorListener?.(error);
+    }
+}

package/dist/connector/host-connector.js

@@ -13,6 +13,7 @@ import { hostWebSocketUrl, resolveHostRelayUrl } from '../relay-urls.js';
 import { resolveSocketPath } from '../socket-discovery.js';
 import { resolveHostPalette } from '../terminal-palette.js';
 import { randomToken } from 'herdr-remote-relay/state';
+import { openAdminTabFor } from './admin-tab.js';
 import { AgentWatch } from './agent-watch.js';
 import { FontServer } from './font-server.js';
 import { acquireHostLock, releaseHostLock } from './lock.js';
@@ -185,10 +186,19 @@ export class HostConnector {
                 password: this.relayPassword || null,
                 hostname: os.hostname(),
                 platform: process.platform,
+                ...(process.platform === 'win32' &&
+                    (process.env.MSYSTEM || /(?:^|[\\/])(?:bash|sh)(?:\.exe)?$/i.test(process.env.SHELL || ''))
+                    ? { shellProfile: 'git-bash' }
+                    : {}),
                 arch: process.arch,
                 terminalPalette: this.terminalPalette || null,
                 terminalFont: this.font.publicFont(),
-                capabilities: [CAPABILITY.hostHandoff, CAPABILITY.idleHeartbeat, CAPABILITY.binaryFrameV2],
+                capabilities: [
+                    CAPABILITY.hostHandoff,
+                    CAPABILITY.idleHeartbeat,
+                    CAPABILITY.binaryFrameV2,
+                    ...(process.platform === 'win32' ? [CAPABILITY.adminTabs] : []),
+                ],
             });
             // The relay sends host_ready with the current browser count. No business
             // heartbeat is started until that message says somebody is watching.
@@ -274,6 +284,12 @@ export class HostConnector {
                 return this.startSession(message);
             case 'herdr_start':
                 return this.sessions.startHerdrFor(streamOf(message));
+            case 'admin_tab_open':
+                return openAdminTabFor(streamOf(message), {
+                    socketPath: this.socketPath,
+                    language: this.config.ui?.language,
+                    send: (payload) => sendJson(this.ws, payload),
+                });
             case 'session_stop': {
                 const streamId = streamOf(message);
                 if (streamId)

package/dist/connector/sessions.js

@@ -11,6 +11,8 @@ import { streamOf } from './wire.js';
  * session the user actually used and then left.
  */
 const FAST_FAILURE_MS = 1500;
+/** Coalesce Windows ConPTY's many small output chunks before they reach the relay. */
+const WINDOWS_OUTPUT_BATCH_MS = 4;
 /** How many broken starts in a row before we stop calling them exits. */
 export const FAST_FAILURE_LIMIT = 3;
 export class Sessions {
@@ -214,12 +216,17 @@ export class Sessions {
             startedAtMs: Date.now(),
             pendingOutput: [],
             flushImmediate: null,
+            flushTimeout: null,
         };
         const flushOutput = () => {
             if (session.flushImmediate) {
                 clearImmediate(session.flushImmediate);
                 session.flushImmediate = null;
             }
+            if (session.flushTimeout) {
+                clearTimeout(session.flushTimeout);
+                session.flushTimeout = null;
+            }
             if (session.pendingOutput.length === 0)
                 return;
             const payload = Buffer.concat(session.pendingOutput);
@@ -237,10 +244,14 @@ export class Sessions {
                     if (chunk.length === 0)
                         return;
                     session.pendingOutput.push(chunk);
-                    // Coalesce burst output from the same tick into a single frame to reduce
-                    // packet overhead without introducing timer latency.
-                    if (!session.flushImmediate)
-                        session.flushImmediate = setImmediate(flushOutput);
+                    if (!session.flushImmediate && !session.flushTimeout) {
+                        if (process.platform === 'win32') {
+                            session.flushTimeout = setTimeout(flushOutput, WINDOWS_OUTPUT_BATCH_MS);
+                        }
+                        else {
+                            session.flushImmediate = setImmediate(flushOutput);
+                        }
+                    }
                 },
                 onExit: ({ exitCode }) => {
                     if (this.byStream.get(streamId) !== session)
@@ -362,5 +373,9 @@ function discardOutput(session) {
         clearImmediate(session.flushImmediate);
         session.flushImmediate = null;
     }
+    if (session.flushTimeout) {
+        clearTimeout(session.flushTimeout);
+        session.flushTimeout = null;
+    }
     session.pendingOutput = [];
 }

package/dist/i18n/en.js

@@ -84,6 +84,22 @@ const en = {
     'services.logEmpty': 'No logs.',
     'services.logRelay': 'Relay',
     'services.logHost': 'Host connector',
+    'adminBroker.windowsOnly': 'The administrator terminal broker only runs on Windows.',
+    'adminBroker.needsElevation': 'Open the Windows TUI and choose Set up admin terminal access. Approve the one-time Windows prompt under the same account as Herdr Remote.',
+    'adminBroker.title': 'Admin terminal broker',
+    'adminBroker.checking': 'Checking…',
+    'adminBroker.ready': 'Ready',
+    'adminBroker.notReady': 'Not configured or stopped',
+    'adminBroker.install': 'Set up admin terminal access',
+    'adminBroker.uninstall': 'Remove admin terminal access',
+    'adminBroker.installDone': 'Admin terminal broker setup task registered.',
+    'adminBroker.uninstallDone': 'Admin terminal broker setup task removed.',
+    'adminBroker.elevationCancelled': 'Administrator approval was declined; no changes were made.',
+    'adminBroker.setupFailed': 'Could not configure the administrator terminal broker.',
+    'adminBroker.tuiHint': 'Set this up once. Windows asks for administrator approval; later WebUI admin terminals open without UAC.',
+    'adminShell.needsTerminal': 'admin-shell must run in a terminal.',
+    'adminShell.brokerUnavailable': 'The administrator terminal broker is not running. Open the herdr-remote TUI, go to Keep-alive, and choose Set up admin terminal access.',
+    'adminShell.tabLabel': 'Admin',
     'relay.title': 'Relay settings',
     'relay.settings': 'Settings',
     'relay.locked': 'fixed',

package/dist/i18n/zh.js

@@ -83,6 +83,22 @@ const zh = {
     'services.logEmpty': '暂无日志。',
     'services.logRelay': 'Relay',
     'services.logHost': '主机连接器',
+    'adminBroker.windowsOnly': '管理员终端 broker 只支持 Windows。',
+    'adminBroker.needsElevation': '请打开 Windows TUI 并选择“设置管理员终端”，使用运行 Herdr Remote 的同一账户批准一次 Windows 提权提示。',
+    'adminBroker.title': '管理员终端 broker',
+    'adminBroker.checking': '正在检查…',
+    'adminBroker.ready': '已就绪',
+    'adminBroker.notReady': '尚未设置或未运行',
+    'adminBroker.install': '设置管理员终端',
+    'adminBroker.uninstall': '移除管理员终端设置',
+    'adminBroker.installDone': '管理员终端 broker 任务已注册。',
+    'adminBroker.uninstallDone': '管理员终端 broker 任务已移除。',
+    'adminBroker.elevationCancelled': '未批准管理员权限，未进行更改。',
+    'adminBroker.setupFailed': '管理员终端 broker 设置失败。',
+    'adminBroker.tuiHint': '只需设置一次。Windows 会请求管理员授权；之后 WebUI 新建管理员终端不再弹出 UAC。',
+    'adminShell.needsTerminal': 'admin-shell 必须在终端中运行。',
+    'adminShell.brokerUnavailable': '管理员终端 broker 尚未运行。请打开 herdr-remote TUI，进入「保活」并选择「设置管理员终端」。',
+    'adminShell.tabLabel': '管理员',
     'relay.title': 'Relay 设置',
     'relay.settings': '设置',
     'relay.locked': '固定',

package/dist/pty-session.js

@@ -10,10 +10,11 @@ class PtySession {
     cwd;
     socketPath;
     platform;
+    fastWindowsPty;
     spawnPty;
     terminal;
     startedAt;
-    constructor({ command, args = [], cwd = os.homedir(), socketPath, platform = process.platform, spawn: spawnPty = pty.spawn, } = {}) {
+    constructor({ command, args = [], cwd = os.homedir(), socketPath, platform = process.platform, spawn: spawnPty = pty.spawn, fastWindowsPty = false, } = {}) {
         if (typeof command !== 'string' || command.length === 0)
             throw new TypeError('command must be a non-empty string');
         if (!Array.isArray(args) || !args.every((arg) => typeof arg === 'string'))
@@ -23,6 +24,7 @@ class PtySession {
         this.cwd = cwd;
         this.socketPath = socketPath;
         this.platform = platform;
+        this.fastWindowsPty = fastWindowsPty;
         this.spawnPty = spawnPty;
         this.terminal = null;
         this.startedAt = null;
@@ -48,16 +50,18 @@ class PtySession {
     start({ cols, rows, onData, onExit }) {
         if (this.terminal)
             throw new Error('PTY session already started');
-        // The bundled ConPTY preserves Kitty sequences older system ConPTY drops,
-        // which is why Herdr embeds it too. System ConPTY's kill() forks a
-        // console-list helper without windowsHide, which flashes a window here.
+        // The Herdr UI needs the bundled ConPTY's Kitty and mouse reporting.
         this.terminal = this.spawnPty(this.command, this.args, {
             name: 'xterm-256color',
             cols: PtySession.clampDimension(cols, PtySession.DEFAULT_COLS),
             rows: PtySession.clampDimension(rows, PtySession.DEFAULT_ROWS),
             cwd: this.cwd,
             env: PtySession.childEnv(this.socketPath),
-            ...(this.platform === 'win32' ? { useConptyDll: true } : {}),
+            ...(this.platform === 'win32'
+                ? this.fastWindowsPty
+                    ? { useConpty: false }
+                    : { useConptyDll: true }
+                : {}),
         });
         this.startedAt = new Date().toISOString();
         const terminal = this.terminal;

package/dist/tui/api.js

@@ -19,6 +19,16 @@ import * as keepalive from '../keepalive/index.js';
 import { canSelfUpdate, checkForUpdate, compareVersions, currentVersion, updateChecksEnabled, installKind, performUpdate, } from '../updater.js';
 import { checkForRelayUpdate, installedRelayVersion, performRelayUpdate, } from '../relay-updater.js';
 export { detectLocale, listReachableAddresses, MIN_HERDR_VERSION, OFFICIAL_RELAY_URL, isOfficialRelay, selectedMode, canSelfUpdate, checkForUpdate, compareVersions, currentVersion, updateChecksEnabled, installKind, performUpdate, checkForRelayUpdate, installedRelayVersion, performRelayUpdate, runsLocalRelay, bindAddress, configExists, configPath, createDraft, createTranslator, ensureRuntime, extractPairingCode, fieldsForMode, fullStatus, getField, getFieldPlaceholder, herdrVersion, keepalive, loadConfig, pair, readLogTail, regenerateHostIdentity, requiresRestart, restartAll, saveDraft, setField, setRelayPassword, startAll, stateDir, stopAll, whileServicesStopped, };
+export async function adminBrokerStatus({ waitForStart = false } = {}) {
+    if (process.platform !== 'win32')
+        return false;
+    const broker = await import('../connector/admin-broker.js');
+    return waitForStart ? broker.waitForAdminBroker() : broker.adminBrokerStatus();
+}
+export async function configureAdminBroker(action, t) {
+    const setup = await import('../connector/admin-broker-setup.js');
+    return setup.configureAdminBroker(action, t);
+}
 /** The command that starts a matching relay, ready to paste on the server. */
 export function relayStartCommand(config, password) {
     const publicUrl = config.relay.remoteUrl

package/dist/tui/screens/Keepalive.js

@@ -1,13 +1,31 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from 'react';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
 import { Box, Text, useInput } from 'ink';
 import { theme } from '../theme.js';
 import { Message, Panel, Row, Selectable, StatusDot } from '../components/common.js';
 import { ChoiceList } from './Relay.js';
-import { KEEPALIVE_MANAGERS, keepalive, saveDraft, setField } from '../api.js';
+import { KEEPALIVE_MANAGERS, adminBrokerStatus, configureAdminBroker, keepalive, saveDraft, setField, } from '../api.js';
 export function Keepalive({ ctx }) {
     const { t, status, draft, editingId } = ctx;
     const [selected, setSelected] = useState('install');
+    const [brokerReady, setBrokerReady] = useState(null);
+    useEffect(() => {
+        if (process.platform !== 'win32')
+            return undefined;
+        let cancelled = false;
+        adminBrokerStatus()
+            .then((available) => {
+            if (!cancelled)
+                setBrokerReady(available);
+        })
+            .catch(() => {
+            if (!cancelled)
+                setBrokerReady(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
     const current = status?.keepalive;
     const entries = [
         { id: 'install', label: t('keepalive.install') },
@@ -17,12 +35,38 @@ export function Keepalive({ ctx }) {
         ...(process.platform === 'linux' && current?.manager === 'systemd' && !current?.linger
             ? [{ id: 'linger', label: t('keepalive.enableLinger') }]
             : []),
+        ...(process.platform === 'win32'
+            ? [
+                { id: 'adminBrokerInstall', label: t('adminBroker.install') },
+                { id: 'adminBrokerUninstall', label: t('adminBroker.uninstall') },
+            ]
+            : []),
     ];
     const activate = (id) => {
         if (id === 'manager') {
             ctx.setEditing('keepaliveManager');
             return;
         }
+        if (id === 'adminBrokerInstall' || id === 'adminBrokerUninstall') {
+            const action = id === 'adminBrokerInstall' ? 'install' : 'uninstall';
+            ctx.run(async () => {
+                let ready = false;
+                try {
+                    await configureAdminBroker(action, t);
+                    ready = action === 'install' && (await adminBrokerStatus({ waitForStart: true }));
+                }
+                catch (error) {
+                    if (error.code === 'ELEVATION_CANCELLED') {
+                        ctx.notify((t) => t('adminBroker.elevationCancelled'), 'info');
+                        return;
+                    }
+                    throw error;
+                }
+                setBrokerReady(ready);
+                ctx.notify((t) => t(`adminBroker.${action}Done`), 'success');
+            });
+            return;
+        }
         ctx.run(async () => {
             if (id === 'install') {
                 if (keepalive.detectManager(ctx.config.keepalive.manager) === 'windows-service')
@@ -88,7 +132,9 @@ export function Keepalive({ ctx }) {
                                     ? t('common.running')
                                     : current?.installed
                                         ? t('common.installed')
-                                        : t('common.notInstalled')] })] }) }), current?.unitPath ? (_jsx(Row, { label: t('keepalive.unitPath'), children: _jsx(Text, { color: theme.muted, children: current.unitPath }) })) : null, _jsx(Box, { marginTop: 1, flexDirection: "column", children: entries.map((entry) => (_jsx(Selectable, { selected: selected === entry.id, onSelect: () => {
+                                        : t('common.notInstalled')] })] }) }), process.platform === 'win32' ? (_jsxs(_Fragment, { children: [_jsx(Row, { label: t('adminBroker.title'), children: _jsx(Text, { color: brokerReady ? theme.ok : theme.warn, children: brokerReady === null
+                                ? t('adminBroker.checking')
+                                : t(brokerReady ? 'adminBroker.ready' : 'adminBroker.notReady') }) }), _jsx(Text, { color: theme.muted, children: t('adminBroker.tuiHint') })] })) : null, current?.unitPath ? (_jsx(Row, { label: t('keepalive.unitPath'), children: _jsx(Text, { color: theme.muted, children: current.unitPath }) })) : null, _jsx(Box, { marginTop: 1, flexDirection: "column", children: entries.map((entry) => (_jsx(Selectable, { selected: selected === entry.id, onSelect: () => {
                         setSelected(entry.id);
                         activate(entry.id);
                     }, onHover: () => setSelected(entry.id), children: entry.label }, entry.id))) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [current?.manager === 'systemd' ? (_jsx(Text, { color: current.linger ? theme.muted : theme.warn, children: current.linger ? t('keepalive.lingerEnabled') : t('keepalive.lingerDisabled') })) : null, current?.manager === 'supervisor' ? (_jsx(Text, { color: theme.warn, children: t('keepalive.fallbackNote') })) : null, current?.manager === 'windows-task' ? (_jsx(Text, { color: theme.muted, children: t('keepalive.windowsTaskNote') })) : null, current?.manager === 'windows-service' ? (_jsx(Text, { color: theme.warn, children: t('keepalive.serviceNote') })) : null, _jsx(Text, { color: theme.muted, children: t('keepalive.logsHint', { command: status?.logsHint ?? '' }) })] }), _jsx(Message, { text: ctx.message?.text ?? null, level: ctx.message?.level ?? 'info' })] }));

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "herdr.remote.web"
 name = "Herdr Remote Web"
-version = "0.2.25"
+version = "0.2.27"
 min_herdr_version = "0.9.1"
 description = "Browser access to Herdr workspaces via local or self-hosted relay"
 platforms = ["linux", "macos", "windows"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-remote",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "description": "Browser access to Herdr workspaces: plugin, host connector, and configuration TUI",
   "license": "MIT",
   "type": "module",