handmux 0.27.2 → 0.29.0

package/dist/src/cli/i18n/zh.js

@@ -1,5 +1,47 @@
 // 中文字典。键与 en.js 一一对应;缺键会自动回退到英文。命令名、flag、隧道名等字面量保持英文(它们是要照抄输入的)。
 export default {
+    'auth.section': '认证与安全',
+    'auth.trusted': '可信设备保护',
+    'auth.token': 'Token 登录',
+    'auth.manageHint': '保护开关只能通过 CLI 管理；设备和访问地址可在 Web 设置中查看和管理。',
+    'auth.noDevices': '还没有已授权设备。请在目标浏览器打开 Handmux，再在这台电脑运行 handmux auth device add。',
+    'auth.access': '设备授权：先在目标浏览器打开 Handmux，再在这台电脑运行 handmux auth device add，并按提示确认。',
+    'auth.warning': '⚠ 可信设备保护未开启：当前只凭 Token 即可访问，建议运行 handmux auth device on 开启。',
+    'auth.addressWarning': '⚠ 可信地址保护未开启：任何地址都可以尝试连接，建议运行 handmux auth address on 开启。',
+    'auth.deviceDisableConfirm': '⚠ 关闭可信设备保护会增加安全风险：之后只需 Token 即可访问。确认要关闭吗？',
+    'auth.addressDisableConfirm': '⚠ 关闭可信地址保护会增加安全风险：任何地址都可以尝试连接。确认要关闭吗？',
+    'auth.code': '请输入目标浏览器显示的 6 位验证码',
+    'auth.codeInvalid': '请输入正好 6 位数字。',
+    'auth.claimed': '已找到这次授权申请。请在 5 分钟内设置设备名称和有效期，确认后浏览器才能登录。',
+    'auth.origin': '访问地址',
+    'auth.name': '设备名称',
+    'auth.expire': '授权有效期',
+    'auth.custom': '自定义',
+    'auth.never': '不限期',
+    'auth.duration': '请输入有效期，例如 1h、7d、30d，或 never',
+    'auth.confirm': '确认授权这台浏览器吗？',
+    'auth.canceled': '已取消本次授权。',
+    'auth.safety': '只确认你正在添加的浏览器；不要输入别人发来的验证码。',
+    'auth.invalidName': '设备名称需为 1–80 个字符，且不能包含控制字符。',
+    'auth.invalidDuration': '请输入有效期，例如 1h、7d、30d 或 never。',
+    'auth.error.unavailable': '无法连接 Handmux 授权服务，请确认 Handmux 正在运行后重试。',
+    'auth.error.invalidCommand': '授权操作无效，请重试。',
+    'auth.error.codeInvalid': '验证码无效、已过期或已使用，请在浏览器重新申请。',
+    'auth.error.rateLimit': '验证码尝试次数过多，请稍后再试。',
+    'auth.error.pairingGone': '这次授权申请已不存在或已过期，请在浏览器重新申请验证码。',
+    'auth.error.deviceNotFound': '找不到这个设备，请先运行 handmux auth device list 查看设备 ID。',
+    'auth.error.deviceInactive': '设备已过期或解除绑定，请重新授权。',
+    'auth.error.conflict': '设备信息已被其他操作修改，请重新查看设备后再试。',
+    'auth.error.invalidEdit': '请至少提供 --name 或 --expire。',
+    'auth.error.invalidVersion': '设备信息已更新，请重新查看设备后再试。',
+    'auth.error.pairingCapacity': '待处理的授权申请太多，请稍后再试。',
+    'auth.error.tokenRequired': '请先提供 Token，再进行授权操作。',
+    'auth.error.deviceRequired': '请先授权这台浏览器，再开启可信设备保护。',
+    'auth.error.expiryCliOnly': '设备有效期只能通过服务器上的 handmux CLI 修改。',
+    'auth.error.invalidOrigin': '访问地址格式不正确，请提供完整的 http(s) 地址。',
+    'auth.error.originLimit': '可信访问地址已达到上限，请先删除一个再添加。',
+    'auth.error.sessionInvalid': '当前设备授权已失效，请重新配对。',
+    'auth.error.controlFailed': '授权操作未完成，请检查 Handmux 状态后重试。',
     // 通用
     'err.generic': '✗ {msg}',
     'err.configNotFound': '✗ --config {path}:找不到该文件',
@@ -107,7 +149,7 @@ export default {
     'access.pending': '(等待中…)',
     'access.lan': '  📶 局域网 {url}',
     'access.local': '  💻 本机   {url}',
-    'access.token': '  🔑 令牌   {token}',
+    'access.token': '  🔑 Token 登录   {token}',
     'access.reachable': '  ✓ 可访问',
     'access.unreachable': '  ⚠ 隧道已起,但 {url} 没有响应 —— 检查服务端的反向代理 / DNS',
     'access.hint': '  handmux status | stop',
@@ -178,6 +220,7 @@ export default {
     'setup.askSshHost': 'ssh 主机(user@host[:port])',
     'setup.askRemotePort': 'ssh 主机上的远程端口',
     'setup.askPublicUrl': '公网地址,http(s):// 按情况填(留空 = http://host:remotePort)',
+    'setup.askDirectPublicUrl': '自定义访问地址(填你自己的反向隧道或代理地址;留空 = 仅本机 / 局域网直连)',
     'setup.natappGuide': '去哪拿 authtoken:到 https://natapp.cn 免费注册 → 新建一条隧道 → 复制它的 authtoken(免费额度够上手)。',
     'setup.cpolarGuide': '去哪拿 authtoken:到 https://cpolar.com 免费注册 → 打开后台 → 验证/Verify → 复制你的 authtoken。',
     'setup.askAuthtoken': 'authtoken',
@@ -193,19 +236,19 @@ export default {
     'setup.secConnection': '连接',
     'setup.secName': '名称',
     'setup.secPort': '端口',
-    'setup.secToken': '令牌',
+    'setup.secToken': 'Token 登录',
     'setup.secBrowser': '网页预览器',
     'setup.browserOff': '未配置 · 仅手机直连',
     'setup.askBrowserDomain': '网页预览器代理域名（留空 = 仅手机直连）',
     'setup.browserAbout': '填写代理域名（如 preview.example.com），并将其通配子域以 HTTPS 路由到 Handmux；留空则仅使用手机直连。',
-    'setup.tokenAuto': '自动 · 每次启动新生成',
-    'setup.tokenCustom': '自定义令牌…',
-    'setup.tokenRandom': '随机生成一个',
-    'setup.tokenReset': '恢复自动(每次启动新生成)',
-    'setup.askToken': '访问令牌 —— 会出现在手机打开的网址里',
-    'setup.tokenGenerated': '新令牌:{token}',
-    'setup.valToken': '请输入令牌',
-    'setup.valTokenSpace': '不能有空格 —— 令牌会放进网址',
+    'setup.tokenAuto': '已保存（Token 不会自动更换）',
+    'setup.tokenCustom': '修改Token…',
+    'setup.tokenRandom': '生成并保存新的随机 Token',
+    'setup.tokenReset': 'Token 不会自动更换',
+    'setup.askToken': 'Token —— 与可信设备同时用于登录',
+    'setup.tokenGenerated': '新的Token:{token}',
+    'setup.valToken': '请输入Token',
+    'setup.valTokenSpace': '不能有空格 —— 请在登录页单独输入 Token',
     'setup.secLanguage': '命令行语言 / CLI language',
     'setup.secPush': '推送',
     'setup.secVoice': '语音',
@@ -235,6 +278,7 @@ export default {
     'setup.valRequired': '{label} 不能为空',
     'setup.valHost': '请输入有效域名(如 myapp.example.com)',
     'setup.valPreviewDomain': '只填域名，如 preview.example.com；不要填 http://、https://、端口或 *.',
+    'setup.valPublicUrl': '请输入完整的 http(s) 地址，例如 https://handmux.example.com（不要带路径或凭据）',
     'setup.valContact': '请填 mailto:you@example.com 或 https://你的站点(要真实域名 —— 苹果会拒收假域名)',
     'setup.sumTemp': '临时',
     'setup.sumFixed': '固定',
@@ -247,6 +291,7 @@ export default {
     'setup.connSshHost': 'SSH 主机',
     'setup.connRemotePort': '远程端口',
     'setup.connPublicUrl': '公网地址',
+    'setup.connDirectAuto': '(留空 = 本机 / 局域网直连)',
     'setup.connJump': '跳板机',
     'setup.connDomain': '域名',
     'setup.connRegion': '区域',
@@ -356,6 +401,16 @@ export default {
   handmux stop | restart | status
   handmux logs [--follow] [--lines N]
   handmux push <标题> <正文>    从脚本推一条通知到手机（--session 会话 · --device 设备key · --tag · --url）
+  handmux auth device status   查看设备保护状态和设备列表
+  handmux auth device on|off   开启或关闭设备保护
+  handmux auth device add      交互式授权浏览器（自动化使用 --code、--name 和 --expire）
+  handmux auth device list     列出完整设备 ID、名称、有效期和访问时间
+  handmux auth device edit <id>   修改设备名称或有效期
+  handmux auth device revoke <id>  立即撤销指定设备
+  handmux auth address status  查看可信地址保护状态和地址列表
+  handmux auth address on|off  开启或关闭可信地址保护
+  handmux auth address add <origin>     添加访问地址
+  handmux auth address remove <origin>  删除访问地址
   handmux codex [参数...]      启动与对话视图同步的 Codex TUI
   handmux pi [参数...]         原样传递参数并启动 Pi
   handmux agent [list]         查看支持的 Agent 接入状态
@@ -383,7 +438,7 @@ start flag(括号内为对应环境变量):
   --tunnel none|cloudflare|cloudflare-named|ssh|natapp|cpolar   暴露方式(默认:none)
   --port N                      服务端口(HANDMUX_PORT,默认:19999)
   --host H                      绑定地址(HANDMUX_HOST,默认:0.0.0.0)
-  --token S                     鉴权令牌(HANDMUX_TOKEN,默认:每次启动自动生成)
+  --token S                     鉴权令牌(HANDMUX_TOKEN,默认:复用已有或首次生成)
   --name "My Box"               浏览器标签 + 主屏图标里的应用名(HANDMUX_APP_NAME)
   --public-url URL              对外公布的公网地址(HANDMUX_PUBLIC_URL;任意隧道均可,包括自建的 none;
                                 ssh 默认 http://host:remotePort;natapp/cpolar 填你的固定/保留域名 ——

package/dist/src/cli/options.js

@@ -64,7 +64,7 @@ export function sshPublicFallback(sshHost, remotePort) {
     const host = sshHost.replace(/^[^@]*@/, '').replace(/:\d+$/, '');
     return `http://${host}:${remotePort}`;
 }
-export function resolveConfig(flags = {}, fileCfg = {}, env = process.env, gen = defaultGen) {
+export function resolveConfig(flags = {}, fileCfg = {}, env = process.env, gen = defaultGen, authDefaults = {}) {
     const pick = (key, ...fallbacks) => {
         for (const v of [flags[key], fileCfg[key], ...fallbacks])
             if (v !== undefined && v !== null)
@@ -82,7 +82,7 @@ export function resolveConfig(flags = {}, fileCfg = {}, env = process.env, gen =
         port,
         name: optionalString(pick('name', env.HANDMUX_APP_NAME), 'name'),
         host: optionalString(pick('host', env.HANDMUX_HOST, '0.0.0.0'), 'host') ?? '0.0.0.0',
-        token: optionalString(pick('token', env.HANDMUX_TOKEN), 'token') ?? gen(),
+        token: optionalString(pick('token', env.HANDMUX_TOKEN, authDefaults.token), 'token') ?? gen(),
         foreground: !!pick('foreground', false),
         qr: pick('qr', true) !== false,
         // Unified config — what used to live in .env. The supervisor injects these into the server child's
@@ -194,15 +194,9 @@ function resolvePublicUrl(flags, fileCfg, env, tunnel) {
         return env.HANDMUX_PUBLIC_URL;
     return null;
 }
-// Default token: 8 chars from a typing-friendly alphabet (lowercase + digits, look-alikes 0/o/1/l dropped)
-// so it's quick to thumb in on a phone. A user-supplied token (flag/config/env) is used verbatim — any
-// length, never regenerated. 8 chars over a 32-char alphabet ≈ 40 bits, fine for a single secret URL.
-const TOKEN_ALPHABET = '23456789abcdefghijkmnpqrstuvwxyz';
+// 192 random bits for new credentials; configured legacy tokens remain unchanged.
 export function defaultGen() {
-    let s = '';
-    for (let i = 0; i < 8; i++)
-        s += TOKEN_ALPHABET[crypto.randomInt(TOKEN_ALPHABET.length)];
-    return s;
+    return crypto.randomBytes(24).toString('base64url');
 }
 function trace(flags, fileCfg, env, cfgPath, key, envKey, def) {
     if (flags[key] != null)
@@ -216,7 +210,7 @@ function trace(flags, fileCfg, env, cfgPath, key, envKey, def) {
 // Build the rows for `handmux config`: the value each key WOULD resolve to plus where it came from.
 // Lenient (never throws — unlike resolveConfig — so a half-finished config still prints) and secret-safe
 // (token masked; push/voice shown only as on/off). Tunnel-specific rows appear only for the live tunnel.
-export function explainConfig(flags = {}, fileCfg = {}, cfgPath = null, env = process.env) {
+export function explainConfig(flags = {}, fileCfg = {}, cfgPath = null, env = process.env, authDefaults = {}) {
     const rows = [];
     const mask = (value) => (String(value).length <= 8 ? '••••' : `••••${String(value).slice(-4)}`);
     const add = (key, traced, display) => {
@@ -230,8 +224,8 @@ export function explainConfig(flags = {}, fileCfg = {}, cfgPath = null, env = pr
     add('name', name, name.value == null ? '(default)' : String(name.value));
     const lang = trace(flags, fileCfg, env, cfgPath, 'lang', 'HANDMUX_LANG', null);
     add('lang', lang, lang.value == null ? '(auto — shell locale)' : String(lang.value));
-    const token = trace(flags, fileCfg, env, cfgPath, 'token', 'HANDMUX_TOKEN', null);
-    add('token', token, token.value == null ? '(generated each start)' : mask(token.value));
+    const token = trace(flags, fileCfg, env, cfgPath, 'token', 'HANDMUX_TOKEN', authDefaults.token ?? null);
+    add('token', token, token.value == null ? '(generated on first start)' : mask(token.value));
     // publicUrl honours the same cross-tunnel guard as resolveConfig (file value only when tunnel matches).
     const t = tunnel.value;
     let pub = trace(flags, fileCfg, env, cfgPath, 'publicUrl', 'HANDMUX_PUBLIC_URL', null);

package/dist/src/cli/pushCmd.js

@@ -1,9 +1,11 @@
+import fs from 'node:fs';
 // `handmux push <title> <body> [--session X]... [--device K]... [--tag T] [--url U]` — fire one
 // notification to the phone through the already-running server (loopback + the server's own token).
 // Scope is mutually exclusive: --device (by key) or --session, else all. Pure parse + injectable
 // runner so it unit-tests without spawning or real fetch.
 import { readState } from './state.js';
 import { sanitizeNotificationUrl } from '../urlPolicy.js';
+import { authSocketPath, connectAuthControl } from '../deviceAuth/control.js';
 const collect = (acc, value) => acc.concat(String(value ?? '').split(',').map((item) => item.trim()).filter(Boolean));
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const finiteNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : 0;
@@ -59,22 +61,33 @@ export async function runPush({ argv, home, fetchImpl = globalThis.fetch, log =
         return 1;
     }
     const st = readState(home);
-    if (!st || typeof st.localUrl !== 'string' || !st.localUrl
-        || typeof st.token !== 'string' || !st.token) {
+    if (!st || typeof st.localUrl !== 'string' || !st.localUrl || typeof st.token !== 'string' || !st.token) {
         err('handmux is not running — run `handmux start` first.');
         return 1;
     }
     try {
-        const res = await fetchImpl(`${st.localUrl}/api/push/send-local`, {
-            method: 'POST',
-            headers: { Authorization: `Bearer ${st.token}`, 'Content-Type': 'application/json' },
-            body: JSON.stringify(parsed),
-        });
-        if (!res.ok) {
-            err(`push failed: ${res.status ?? 'unknown'}`);
-            return 1;
+        let raw;
+        if (fs.existsSync(authSocketPath(home))) {
+            const control = await connectAuthControl(home);
+            try {
+                raw = await control.request({ op: 'push', body: parsed });
+            }
+            finally {
+                control.close();
+            }
+        }
+        else {
+            const res = await fetchImpl(`${st.localUrl}/api/push/send-local`, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${st.token}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify(parsed),
+            });
+            if (!res.ok) {
+                err(`push failed: ${res.status ?? 'unknown'}`);
+                return 1;
+            }
+            raw = await res.json();
         }
-        const raw = await res.json();
         const out = isRecord(raw) ? raw : {};
         if (out.configured === false) {
             err('push is not configured (no VAPID keys) — run `handmux setup`.');

package/dist/src/cli/setupModel.js

@@ -75,8 +75,8 @@ export function findTunnelId(listJsonOut, name) {
 // The config keys the wizard owns: everything it can set. mergeConfig wipes these from the existing config
 // before re-applying the answers, so switching a tunnel (or clearing an optional field) cleanly drops the
 // old value instead of leaving a stale field behind. Anything NOT here (staticDir, uploadExts…) is
-// preserved untouched. `token` IS owned so the Token row can pin one AND clear it back to auto — but it
-// round-trips through answersFromConfig, so a re-run that never touches the row still writes it back.
+// preserved untouched. `token` IS owned so the Token can be changed from
+// its sub-page and round-trips through answersFromConfig on every setup run.
 const WIZARD_KEYS = [
     'lang', 'name', 'port', 'tunnel', 'token', 'previewDomain',
     'sshHost', 'remotePort', 'sshJump', 'cfHostname', 'cfTunnelName', 'publicUrl',
@@ -93,9 +93,15 @@ export function configFromAnswers(a) {
     if (a.name)
         cfg.name = a.name;
     if (a.token)
-        cfg.token = a.token; // blank = don't pin one → the server mints a fresh token each start
+        cfg.token = a.token;
     if (a.previewDomain)
         cfg.previewDomain = a.previewDomain;
+    // Direct mode can sit behind a user-managed reverse tunnel or proxy.  Keep
+    // its public entry point in the same `publicUrl` field used by the built-in
+    // tunnel drivers so origin validation and the URL shown by `handmux start`
+    // use one source of truth.
+    if (a.tunnel === 'none' && a.publicUrl)
+        cfg.publicUrl = a.publicUrl;
     if (a.tunnel === 'ssh') {
         cfg.sshHost = a.sshHost;
         cfg.remotePort = a.remotePort;
@@ -138,7 +144,7 @@ export function answersFromConfig(config = {}) {
     const a = {
         lang: optionalString(cfg.lang) || getLocale(),
         name: optionalString(cfg.name) || '',
-        token: optionalString(cfg.token) || '', // '' = not pinned (auto each start); seeded so an untouched re-run rewrites it
+        token: optionalString(cfg.token) || '',
         previewDomain: optionalString(cfg.previewDomain) || '',
         tunnel: isTunnel(cfg.tunnel) ? cfg.tunnel : 'none',
         port: Number(cfg.port) || 19999,
@@ -215,6 +221,21 @@ export function validatePreviewDomain(v) {
         return undefined;
     return /^[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(s) ? undefined : t('setup.valPreviewDomain');
 }
+export function validatePublicUrl(v) {
+    const s = String(v || '').trim();
+    if (!s)
+        return undefined;
+    try {
+        const url = new URL(s);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password
+            || url.pathname !== '/' || url.search || url.hash)
+            return t('setup.valPublicUrl');
+        return undefined;
+    }
+    catch {
+        return t('setup.valPublicUrl');
+    }
+}
 // VAPID subject: Apple (APNs) rejects a fake/.local domain with BadJwtToken, so require a real-looking
 // mailto:you@host.tld or an https:// URL and reject the known-bad .local. Keeps push from silently
 // failing on iOS. (Can't fully validate "real" client-side — this just catches the obvious footguns.)
@@ -226,8 +247,9 @@ export function validateContact(v) {
         return t('setup.valContact');
     return undefined;
 }
-// Access token: it rides in the phone's URL as ?token=…, so require something and reject whitespace (a space
-// would break the link). Length/charset are otherwise up to the user — a pinned token is used verbatim.
+// The Token is entered separately on the login page and is never put in
+// an address or QR code. Keep the value non-empty and whitespace-free so it
+// can be copied without ambiguity.
 export function validateToken(v) {
     const s = String(v || '').trim();
     if (!s)

package/dist/src/cli/setupWizard.js

@@ -17,6 +17,7 @@ import { resolveNatapp, resolveCpolar } from './tunnelClients.js';
 import { t, setLocale } from './i18n/index.js';
 import { intro, outro, note, cancel, select, text, password, confirm, ask, CANCELLED } from './prompt.js';
 import { PrivateStateStore } from '../privateStateStore.js';
+import { installationAuthDefaults } from './authDefaults.js';
 const errorMessage = (error) => {
     if (error instanceof Error)
         return error.message;
@@ -29,15 +30,15 @@ const isTunnel = (value) => (typeof value === 'string' && TUNNELS.includes(value
 // The pure answer↔config model + validators + cloudflared text helpers live in setupModel.js. Imported for
 // the interactive shell below; re-exported so their historical import path (this module) stays valid for
 // callers and tests.
-import { cfConfigYaml, parseTunnelCreate, findTunnelId, mergeConfig, answersFromConfig, summarizeConnection, normalizeVoiceConfig, validatePort, validateHost, validatePreviewDomain, validateNonEmpty, validateContact, validateToken, TUNNEL_KEYS, } from './setupModel.js';
-export { cfConfigYaml, parseTunnelCreate, findTunnelId, configFromAnswers, mergeConfig, answersFromConfig, summarizeConnection, normalizeVoiceConfig, validatePort, validateHost, validatePreviewDomain, validateNonEmpty, validateContact, validateToken, } from './setupModel.js';
+import { cfConfigYaml, parseTunnelCreate, findTunnelId, mergeConfig, answersFromConfig, summarizeConnection, normalizeVoiceConfig, validatePort, validateHost, validatePreviewDomain, validatePublicUrl, validateNonEmpty, validateContact, validateToken, TUNNEL_KEYS, } from './setupModel.js';
+export { cfConfigYaml, parseTunnelCreate, findTunnelId, configFromAnswers, mergeConfig, answersFromConfig, summarizeConnection, normalizeVoiceConfig, validatePort, validateHost, validatePreviewDomain, validatePublicUrl, validateNonEmpty, validateContact, validateToken, } from './setupModel.js';
 function readExisting(file) {
-    try {
-        return new PrivateStateStore(file).readStrict() || {};
-    }
-    catch {
+    if (!fs.existsSync(file))
         return {};
-    }
+    const value = new PrivateStateStore(file).readStrict();
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('expected a JSON object');
+    return value;
 }
 // The hub. Pre-fills from the existing config so a re-run edits/switches rather than starts over; a brand-
 // new config first walks Connection, then everyone lands on the hub (edit any section, then Save/Start/Exit).
@@ -49,9 +50,20 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
         log.error(t('setup.needTty'));
         return null;
     }
-    const existing = readExisting(target);
-    const isNew = !existing || Object.keys(existing).length === 0;
+    let existing;
+    try {
+        existing = readExisting(target);
+    }
+    catch (error) {
+        log.error(t('err.badConfig', { path: target, msg: errorMessage(error) }));
+        return null;
+    }
+    const defaults = installationAuthDefaults(home, target);
+    const { isNew } = defaults;
     let a = answersFromConfig(existing);
+    // Token is a durable factor. If no token exists yet, mint it once and persist it in config.json.
+    if (!a.token)
+        a.token = process.env.HANDMUX_TOKEN ?? defaults.token ?? genToken();
     setLocale(a.lang);
     intro('handmux setup');
     // First run lands the cursor on "Save & start" — the essential step (connection) is done in onboarding and
@@ -67,6 +79,7 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
                 a.lang = await editLanguage(a);
                 note(t('setup.welcome'));
                 a = await editConnection(a, { home, log });
+                await editAuth(a);
             }
             catch (e) {
                 if (e !== CANCELLED)
@@ -81,7 +94,7 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
                     { value: 'connection', label: t('setup.secConnection'), hint: summarizeConnection(a) },
                     { value: 'name', label: t('setup.secName'), hint: a.name || t('setup.default') },
                     { value: 'port', label: t('setup.secPort'), hint: String(a.port) },
-                    { value: 'token', label: t('setup.secToken'), hint: a.token ? maskSecret(a.token) : t('setup.tokenAuto') },
+                    { value: 'auth', label: t('auth.section'), hint: a.token ? maskSecret(a.token) : t('setup.tokenAuto') },
                     { value: 'browser', label: t('setup.secBrowser'), hint: a.previewDomain || t('setup.browserOff') },
                     { value: 'push', label: t('setup.secPush'), hint: a.vapid ? (a.vapid.subject || t('setup.on')) : t('setup.off') },
                     {
@@ -120,8 +133,8 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
                     a.name = await editName(a);
                 else if (choice === 'port')
                     a.port = await editPort(a);
-                else if (choice === 'token')
-                    a.token = await editToken(a);
+                else if (choice === 'auth')
+                    await editAuth(a);
                 else if (choice === 'browser')
                     a.previewDomain = await editBrowserDomain(a);
                 else if (choice === 'language')
@@ -158,6 +171,10 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
 // clack's footer only shows ↑/↓ + Enter, so append the Esc-backs-out hint to each section's entry prompt —
 // otherwise a user inside a section can't tell there's a way back to the hub.
 const withBack = (msg) => `${msg}  ${t('setup.escBack')}`;
+async function editAuth(a) {
+    note(t('auth.manageHint'));
+    a.token = await editToken(a);
+}
 async function editLanguage(a) {
     const lang = await ask(select({
         message: withBack(t('setup.langQ')),
@@ -186,22 +203,19 @@ async function editBrowserDomain(a) {
     }));
     return String(value || '').trim().toLowerCase();
 }
-// The access token — the one secret in the phone's URL. Unset = the server mints a fresh one each start
-// (printed + QR'd), so the link changes every restart; pinning one keeps the same URL. A mini-hub (like
-// push/voice): type your own, generate + pin a strong random one, or reset back to auto. Editing custom
-// pre-fills the current value (so you can read it off); the hub hint masks it. Esc returns to the main hub,
-// keeping the choice. Returns the token string ('' = auto).
+// Token is a durable factor. A mini-hub lets the user keep the
+// current value, replace it with a custom value, or generate a new one. The
+// hub hint masks it and Esc returns without changing it.
 async function editToken(a) {
-    let token = a.token || '';
+    let token = a.token || genToken();
     for (;;) {
         let pick;
         try {
             pick = await ask(select({
                 message: withBack(t('setup.secToken')),
                 options: [
-                    { value: 'custom', label: t('setup.tokenCustom'), hint: token ? maskSecret(token) : t('setup.tokenAuto') },
+                    { value: 'custom', label: t('setup.tokenCustom'), hint: maskSecret(token) },
                     { value: 'random', label: t('setup.tokenRandom') },
-                    { value: 'auto', label: t('setup.tokenReset'), hint: t('setup.tokenAuto') },
                 ],
                 initialValue: 'custom',
             }));
@@ -218,8 +232,6 @@ async function editToken(a) {
                 token = genToken();
                 note(t('setup.tokenGenerated', { token }));
             }
-            else if (pick === 'auto')
-                token = '';
         }
         catch (e) {
             if (e !== CANCELLED)
@@ -240,12 +252,18 @@ function tunnelOptions() {
         { value: 'cpolar', label: 'cpolar', hint: t('setup.hintCpolar') },
     ];
 }
-// Which tunnels have config fields to edit a level deeper (none/cloudflare-quick have nothing to configure).
-const hasConnFields = (tunnel) => ['cloudflare-named', 'ssh', 'natapp', 'cpolar'].includes(tunnel);
+// Which tunnels have config fields to edit a level deeper. Direct mode has an
+// optional public URL for a user-managed reverse tunnel; leaving it blank is
+// still the ordinary LAN/local direct connection.
+const hasConnFields = (tunnel) => ['none', 'cloudflare-named', 'ssh', 'natapp', 'cpolar'].includes(tunnel);
 // The editable field rows for the CURRENT tunnel — the type/mode is chosen a level up (the picker), so this
 // lists ONLY that tunnel's config, values shown and secrets masked. Empty for none / cloudflare-quick.
 function connectionFieldRows(a) {
     const none = t('setup.connNone');
+    if (a.tunnel === 'none')
+        return [
+            { value: 'publicUrl', label: t('setup.connPublicUrl'), hint: a.publicUrl || t('setup.connDirectAuto') },
+        ];
     if (a.tunnel === 'cloudflare-named')
         return [
             { value: 'cfHostname', label: t('setup.connHostname'), hint: a.cfHostname || none },
@@ -345,7 +363,11 @@ async function editConnField(a, field) {
             n.remotePort = Number(await ask(text({ message: t('setup.askRemotePort'), initialValue: String(a.remotePort || a.port), validate: validatePort })));
             break;
         case 'publicUrl':
-            setOpt('publicUrl', await ask(text({ message: t('setup.askPublicUrl'), initialValue: a.publicUrl || '' })));
+            setOpt('publicUrl', await ask(text({
+                message: t(a.tunnel === 'none' ? 'setup.askDirectPublicUrl' : 'setup.askPublicUrl'),
+                initialValue: a.publicUrl || '',
+                validate: validatePublicUrl,
+            })));
             break;
         case 'sshJump':
             setOpt('sshJump', await ask(text({ message: t('setup.askSshJump'), initialValue: a.sshJump || '' })));

package/dist/src/cli/shortcutEditor.js

@@ -1,8 +1,10 @@
+import fs from 'node:fs';
 import { normalizeShortcuts, shortcutIdentity } from '../shortcutConfig.js';
 import { t } from './i18n/index.js';
 import * as prompts from './prompt.js';
 import { acquireLifecycleLock, isAlive, readState } from './state.js';
 import { PrivateStateStore } from '../privateStateStore.js';
+import { authSocketPath, connectAuthControl } from '../deviceAuth/control.js';
 const MODIFIERS = {
     none: { prefixes: [], labels: [] },
     ctrl: { prefixes: ['C-'], labels: ['Ctrl'] },
@@ -281,8 +283,24 @@ export async function runShortcutEditor({ target, log = console, isTTY = process
         throw error;
     }
 }
-export async function applyShortcutsLive({ state, shortcuts, fetchImpl = globalThis.fetch, timeoutMs = 8000, }) {
+export async function applyShortcutsLive({ state, shortcuts, home, fetchImpl = globalThis.fetch, timeoutMs = 8000, }) {
     const stateRecord = recordOf(state);
+    if (home && fs.existsSync(authSocketPath(home))) {
+        if (!home)
+            throw new Error('handmux home is required for the private control socket');
+        const control = await connectAuthControl(home);
+        const timer = setTimeout(() => control.close(), timeoutMs);
+        try {
+            const acknowledgment = await control.request({ op: 'shortcuts', body: { shortcuts } });
+            if (recordOf(acknowledgment)?.ok !== true)
+                throw new Error('invalid server response');
+        }
+        finally {
+            clearTimeout(timer);
+            control.close();
+        }
+        return;
+    }
     if (typeof stateRecord?.localUrl !== 'string' || !stateRecord.localUrl
         || typeof stateRecord.token !== 'string' || !stateRecord.token) {
         throw new Error('running server state is incomplete');
@@ -328,7 +346,7 @@ export async function commitShortcuts({ home, target, shortcuts, acquireLock = a
         if (!state || !isAliveImpl(state.supervisorPid))
             return { cfg, running: false, applied: false };
         try {
-            await applyShortcutsLive({ state, shortcuts: cfg.shortcuts, fetchImpl, timeoutMs });
+            await applyShortcutsLive({ state, shortcuts: cfg.shortcuts, home, fetchImpl, timeoutMs });
             return { cfg, running: true, applied: true };
         }
         catch (error) {

package/dist/src/cli/supervisor.js

@@ -34,11 +34,11 @@ export function lanUrl(port, ifaces = os.networkInterfaces()) {
     }
     return null;
 }
-// The token rides in the query string so the first navigation (or a QR scan) authenticates in one shot.
-export function publicUrlWithToken(base, token) {
-    if (!base)
-        return base;
-    return `${base.replace(/\/$/, '')}/?token=${encodeURIComponent(token)}`;
+// Kept as a source-compatible helper for integrations that imported the old
+// name. Credentials are deliberately never put in a URL; QR and CLI output
+// carry only the address and the browser asks for the Token separately.
+export function publicUrlWithToken(base, _token) {
+    return bareUrl(base);
 }
 // Bare address with no token in it — printed/QR-encoded so a link can be shared or screenshotted without
 // leaking the secret; the token is shown separately for the user to paste in.
@@ -80,8 +80,6 @@ export function supervise(cfg, { home, log = console, spawnChild = defaultSpawnC
         error: null,
     };
     const persist = () => {
-        // Keep the legacy top-level fields during migration, but derive them from the explicit component
-        // machines so `ready` can never outlive the Server process that earned it.
         state.serverPid = components.server.pid;
         state.tunnelPid = components.tunnel.pid;
         state.ready = components.server.phase === 'ready';