@hyzyn/dsh-docker 0.8.1 → 0.9.0-rc.2

package/lib/index.js

@@ -1,9 +1,10 @@
+import { join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { definePlugin, plainConfig, readSettingsEntry, settingsEntryScope, suppressAutoSettingsPage } from '@hyzyn/dsh-kit';
+import { definePlugin, hasSameOriginProof, isLoopbackRequestStrict, originProofHint, plainConfig, readSettingsEntry, settingsEntryScope, suppressAutoSettingsPage } from '@hyzyn/dsh-kit';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import * as dns from 'node:dns';
 import { DockerApi, assertBin, assertImageRef, assertName, assertRef, assertSince, createRunner, parseImageHistoryJson, parseImageHistoryText, parseContainerEvent, parseEventsJson, parseImageInspectJson, parseInspectJson, parsePsJson, parseStatsJson, suggestContainerNames, } from './docker.js';
-import { RemoteExec, setCredentialResolver, sshTarget } from './ssh-exec.js';
+import { RemoteExec, sanitizeJumpSpec, sanitizeProxyCommand, setCredentialResolver, sshTarget } from './ssh-exec.js';
+import { auditLoadedGrants, bindCapabilitySources, capabilityDeniedMessage, capabilityGrantAt, capabilityGranted, capabilityGrantVia, capabilityPaths, createElevationManager, dshHome, sharedGrantStore, } from '@hyzyn/dsh-kit';
 const TARGET_SCHEMA = z.object({
     name: z.string().required(),
     kind: z.union([z.const('local'), z.const('ssh')]).default('local'),
@@ -81,6 +82,13 @@ const MUTATION_SUBROUTES = new Set([
     '/volumes/remove',
     '/volumes/prune',
     '/exec',
+    /*
+     * 就地提权三条（判定条件是**精确子路径** + POST，所以必须逐条列；只写 '/elevate' 的话
+     * /elevate/status 与 /elevate/revoke 就是裸奔的——跨站页面能撤销授权、能对着确认码试错）。
+     */
+    '/elevate',
+    '/elevate/status',
+    '/elevate/revoke',
 ]);
 /** 「这条错误来自目标侧」的标记（见 guardTargetFailures）。 */
 const TARGET_FAILURE = Symbol('dsh-docker.target-failure');
@@ -134,170 +142,12 @@ export function sseFrame(event, data) {
 }
 /** SSE 心跳间隔（毫秒）：注释帧只保活，客户端 EventSource 会忽略。 */
 const SSE_HEARTBEAT_MS = 15_000;
-/** HTTP 路由的 loopback 信任围栏（与 tty / dsh-mcp 同思路）。 */
 /*
- * 环回地址判定（D31）：接受 127/8 全段（BSD/Linux 惯例——整个 127.0.0.0/8 都是
- * 环回，此前只认 127.0.0.1 一个字面量）与 IPv6 等价形式（::1、::ffff: 映射）。
+ * 回环围栏与同源证明：**实现已收敛到 `@hyzyn/dsh-kit`**（2026-09-25，项目级 ROADMAP
+ * 第 1 项）。本包是那段加固档的来源，行为一字未改；D31 / D32 / D80 / D110 / D139 五条
+ * 的成因、时序约束与桌面版例外随实现一起搬到了 `packages/kit/src/http.ts`——**那边的
+ * 注释是唯一归宿**，这里只留指针（否则又是「三处各写一份必然漂」）。
  */
-function isLoopbackAddress(address) {
-    if (address === undefined || address === '')
-        return false;
-    let text = address.toLowerCase();
-    if (text.startsWith('::ffff:'))
-        text = text.slice(7);
-    if (text === '::1')
-        return true;
-    const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(text);
-    return v4 !== null && v4[1] === '127';
-}
-/** 别名 Host 解析结果的缓存与超时（D110）：请求路径里的 DNS 不该每请求都打一次，也不该无限等。 */
-const HOST_LOOPBACK_TTL_MS = 60_000;
-const HOST_LOOPBACK_CACHE_MAX = 64;
-const HOST_LOOPBACK_TIMEOUT_MS = 500;
-const hostLoopbackCache = new Map();
-/**
- * 解析一个主机名是否指向本机（D110）。带 500ms 超时与 60s 的 LRU（别名部署下每个请求都要过一次）。
- * **失败与超时不缓存**：解析器恢复后要立刻生效，而不是把一次抖动钉 60 秒。
- */
-async function lookupHostLoopback(host) {
-    const cached = hostLoopbackCache.get(host);
-    if (cached !== undefined && Date.now() - cached.at <= HOST_LOOPBACK_TTL_MS)
-        return cached.loopback;
-    let timer = null;
-    try {
-        const records = await Promise.race([
-            dns.promises.lookup(host, { all: true }),
-            new Promise((_resolve, reject) => {
-                timer = setTimeout(() => reject(new Error(`DNS 解析超时（>${String(HOST_LOOPBACK_TIMEOUT_MS)}ms）`)), HOST_LOOPBACK_TIMEOUT_MS);
-                timer.unref?.();
-            }),
-        ]);
-        const loopback = records.some((record) => isLoopbackAddress(record.address));
-        if (hostLoopbackCache.size >= HOST_LOOPBACK_CACHE_MAX) {
-            const oldest = hostLoopbackCache.keys().next().value;
-            if (oldest !== undefined)
-                hostLoopbackCache.delete(oldest);
-        }
-        hostLoopbackCache.set(host, { at: Date.now(), loopback });
-        return loopback;
-    }
-    catch {
-        return false;
-    }
-    finally {
-        if (timer !== null)
-            clearTimeout(timer);
-    }
-}
-/**
- * Host 是否指向本机（D31）：字面量环回直接判；主机名 / /etc/hosts 别名走一次带超时的
- * DNS 解析。判不出来就拒绝——围栏宁可误拦一个怪别名，不能放行一个能解析到公网的 Host。
- */
-async function hostResolvesToLoopback(hostname) {
-    const host = hostname.toLowerCase().replace(/\.$/, '');
-    if (host === 'localhost' || host.endsWith('.localhost') || isLoopbackAddress(host))
-        return true;
-    return await lookupHostLoopback(host);
-}
-/**
- * loopback 信任围栏（D31）：字面量环回（绝大多数请求）**同步**判定——保持
- * 「请求进来即建流」的原有时序（SSE 测试与 EventSource 都依赖第一拍就写头）；
- * 只有主机名 / /etc/hosts 别名才走异步 DNS 确认。
- *
- * **来源检查必须在解析 Host 之前**（D80）：别名主机名（`127.0.0.1.nip.io`、`/etc/hosts` 里
- * 的别名）走的是异步分支，若在那里提前 return，`Sec-Fetch-Site` 与 Origin 两段检查会被
- * 整段跳过 —— 围栏等于没设，跨站页面就能写 `/config`（它不要求同源证明）。
- */
-function isLoopbackHttp(req) {
-    if (!isLoopbackAddress(req.socket.remoteAddress))
-        return false;
-    const host = req.headers.host;
-    if (typeof host !== 'string')
-        return false;
-    let hostUrl;
-    try {
-        hostUrl = new URL('http://' + host);
-    }
-    catch {
-        return false;
-    }
-    if (req.headers['sec-fetch-site'] === 'cross-site')
-        return false;
-    const origin = req.headers.origin;
-    if (origin !== undefined) {
-        let sameOrigin = false;
-        try {
-            sameOrigin = new URL(origin).host === hostUrl.host;
-        }
-        catch {
-            sameOrigin = false;
-        }
-        if (!sameOrigin)
-            return false;
-    }
-    const hostname = hostUrl.hostname.toLowerCase().replace(/\.$/, '');
-    if (hostname === 'localhost' || hostname.endsWith('.localhost') || isLoopbackAddress(hostname))
-        return true;
-    return hostResolvesToLoopback(hostname);
-}
-/**
- * 「同源证明」（D32）：变更类与长流端点要求请求带 Origin（浏览器 fetch 对
- * cross-site 一定带）或 Sec-Fetch-Site: same-origin 之一。恶意页面可以用
- * `<img src="GET /images/pull/stream?...">` 触发副作用 / 拉起 docker 子进程，
- * 而旧 Safari / 部分 WebView 既不发 Origin 也不发 Sec-Fetch-Site——这两类端点
- * 对「无来源证明」的请求拒绝；只读端点维持 loopback-only 的原信任模型。
- *
- * **桌面版例外（D139）**：桌面壳把页面发往 `dsh-app://app/api/…` 的请求转给真实宿主时
- * **会删掉 `origin` 与 `sec-fetch-site`**（`app.asar/lib/main.js` 的 `forwardWebRequest`，
- * 只重写 `host` / `cookie`，其余头原样带过去），于是这四条 SSE 与八条变更路由在桌面版
- * **全部** 403——症状是日志 / 统计 / 活动 / 拉取四条流无限「连接中断，正在自动重连…」，
- * 而同一个面板的只读路由（`/containers`、`/inspect`…）照常可用（它们不要求证明）。
- *
- * 桌面壳在这条转发链上**必带宿主会话 Cookie**：`hostCookie` 由 `authenticateWebHost()`
- * 拿 `set-cookie` 换来，取不到时 `forwardWebRequest` 整体 503、根本走不到这里。而浏览器
- * 页面**伪造不了 Cookie 头**——跨站请求带不带它由 SameSite 决定，且现代浏览器一定同时带
- * `sec-fetch-site: cross-site`（已被上一条 loopback 围栏拒掉）。
- *
- * 所以把「两条证明都缺省」收窄成「都缺省 **且** 带宿主 Cookie」：桌面版放行、旧 Safari /
- * 裸 curl 仍然拒。这不是 D32 的松动——本函数从来没挡住本机进程（它们随时可以自带
- * `Origin: http://127.0.0.1:<port>` 过闸），防的一直是**浏览器**，而 Cookie 恰恰是浏览器
- * 侧最不可伪造的那一件。
- */
-function hasSameOriginProof(req) {
-    const site = req.headers['sec-fetch-site'];
-    if (typeof site === 'string' && site === 'same-origin')
-        return true;
-    const origin = req.headers.origin;
-    if (origin !== undefined) {
-        // Origin 出现就一律以它为准：非字符串 / 空串 / 不同源都拒，**不回落**到 Cookie——
-        // 否则一个畸形 Origin 反倒成了绕过同源比对的入口
-        if (typeof origin !== 'string' || origin === '')
-            return false;
-        const host = req.headers.host;
-        if (typeof host !== 'string')
-            return false;
-        try {
-            return new URL(origin).host === host;
-        }
-        catch {
-            return false;
-        }
-    }
-    const cookie = req.headers.cookie;
-    return typeof cookie === 'string' && cookie.trim() !== '';
-}
-/**
- * 403 的成因摘要（D139）：这次桌面版四条流全断，宿主侧**一条日志都没有**，只能靠读客户端
- * 源码 + 拆 `app.asar` 反推。以后同类问题第一眼就能定位：只报这三个头「有没有」，
- * **绝不落 Cookie 的值**（它是宿主会话凭据）。
- */
-function originProofHint(req) {
-    const has = (name) => {
-        const value = req.headers[name];
-        return typeof value === 'string' && value !== '' ? '有' : '无';
-    };
-    return `origin=${has('origin')} sec-fetch-site=${has('sec-fetch-site')} cookie=${has('cookie')}`;
-}
 function writeJson(res, status, body) {
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'referrer-policy': 'no-referrer' });
     res.end(JSON.stringify(body));
@@ -467,6 +317,38 @@ export function mergeTargetSecrets(prev, incoming) {
         return next;
     });
 }
+/**
+ * 两条能力开关的宿主侧授权（见 kit 的 capability.js 与 docs/architecture.md）。
+ *
+ * 两条提权通道：**启动环境变量**（最严，见 kit 的 capability.ts）与**就地提权**（页内点开关 →
+ * 在宿主上落地一个随机名文件 → 免重启生效，见 kit 的 elevation.ts）。HTTP 侧不能凭空打开它们——
+ * 回环围栏与同源证明都拦不住跨站页面与页内脚本（它们能自己填 `Sec-Fetch-Site: same-origin`，
+ * 那是请求头不是凭据），而 docker socket 等价目标主机 root。
+ */
+const CAP_MUTATIONS = { env: 'DSH_DOCKER_ALLOW_MUTATIONS', label: '变更操作' };
+const CAP_EXEC = { env: 'DSH_DOCKER_ALLOW_EXEC', label: 'exec' };
+/**
+ * 客户端/HTTP 用的能力名 → 授权说明。**白名单**：不在表里的一律 400。
+ *
+ * 为什么要这张表：路由收到的 `capability` 是外部字符串，直接拿它当环境变量名去查授权存储，等于让
+ * 请求方决定「查哪个键」——今天查不出问题（存储里只有这两个键），明天就是一类越权。
+ */
+const CAPABILITIES = new Map([
+    ['allowMutations', CAP_MUTATIONS],
+    ['allowExec', CAP_EXEC],
+]);
+/** 未启用时的文案：没授权要说清「怎么授权」，授权了只是没开就说「去开开关」。 */
+function mutationsOffMessage() {
+    return capabilityGranted(CAP_MUTATIONS)
+        ? '变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）'
+        : capabilityDeniedMessage(CAP_MUTATIONS, { inPlace: true });
+}
+/** `exec` 那一档的同款文案。 */
+function execOffMessage() {
+    return capabilityGranted(CAP_EXEC)
+        ? 'exec 未启用（插件配置 → Docker 容器面板 → 允许 exec）'
+        : capabilityDeniedMessage(CAP_EXEC, { inPlace: true });
+}
 /** 把一份任意来源的配置归一成 LiveConfig。 */
 export function normalizeConfig(section) {
     const targets = sanitizeTargets(section.targets);
@@ -475,8 +357,14 @@ export function normalizeConfig(section) {
         enabled: section.enabled !== false,
         announceToAgent: section.announceToAgent !== false,
         dockerBin: assertBin(section.dockerBin),
-        allowMutations: section.allowMutations === true,
-        allowExec: section.allowExec === true,
+        /*
+         * **有效值 = 配置值 && 宿主授权**。折叠在这一处（而不是每个使用点各判一次）的理由：本包
+         * 有二十多处按 `live.allowMutations` 决定「工具注册 / 路由放行 / 面板渲染」，散着判必然
+         * 漏一处——漏掉的那处就是「没授权也能执行」。配置里的 true 不算授权：它与 HTTP 写进去的
+         * 值存在同一个存储里，分不出来源，只认环境变量才是能说清的规则（升级影响见 README）。
+         */
+        allowMutations: section.allowMutations === true && capabilityGranted(CAP_MUTATIONS),
+        allowExec: section.allowExec === true && capabilityGranted(CAP_EXEC),
         execTimeoutSec: clampInt(section.execTimeoutSec, 1, 120, 30),
         pollIntervalSec: clampInt(section.pollIntervalSec, 1, 60, 5),
         logTailDefault: clampInt(section.logTailDefault, 1, 5000, 200),
@@ -517,7 +405,11 @@ export function formatBytes(value) {
     return `${text} ${units[unit] ?? 'B'}`;
 }
 /** 从 tty 的 entry settings 读取连接簿（只读；tty 未安装时为空表）。 */
-function readTtyBooks(settings) {
+/**
+ * 读 tty 连接簿 → 本包的连接规格。**导出仅供单测**（连接簿 → 规格这一跳是「一处配置、两处
+ * 生效」的落地处：漏带 jump / proxyCommand 就是「tty 能连、docker 连不上」那种半吊子状态）。
+ */
+export function readTtyBooks(settings) {
     const out = new Map();
     if (settings === undefined)
         return out;
@@ -542,7 +434,7 @@ function readTtyBooks(settings) {
         const username = typeof item.username === 'string' ? item.username.trim() : '';
         if (name === '' || host === '' || username === '')
             continue;
-        out.set(name, {
+        const spec = {
             host,
             port: typeof item.port === 'number' && Number.isInteger(item.port) ? item.port : 22,
             username,
@@ -551,10 +443,47 @@ function readTtyBooks(settings) {
             password: typeof item.password === 'string' ? item.password : '',
             passphrase: typeof item.passphrase === 'string' ? item.passphrase : '',
             agentForward: item.agentForward === true,
-        });
+        };
+        /*
+         * 跳板机跟着连接簿一起走（本包**不自建跳板机界面**：目标是「一处配置、两处生效」）。
+         * 漏了这一段就是「终端能连、docker 目标连不上」——本项立项时点名的半吊子状态。
+         */
+        const jump = sanitizeJumpSpec(item.jump);
+        if (jump !== undefined)
+            spec.jump = jump;
+        /*
+         * 代理命令同理跟着连接簿走（本包**不自建界面**）。闸门不在这里判：它归 tty settings 的
+         * `allowProxyCommand`，由 `readTtyProxyCommandAllowed()` 现读、在**每次拨号**时求值
+         * （见 RemoteExec 的 options.proxyCommandAllowed）——这样用户一关开关就立刻生效。
+         */
+        const proxyCommand = sanitizeProxyCommand(item.proxyCommand);
+        if (proxyCommand !== undefined)
+            spec.proxyCommand = proxyCommand;
+        out.set(name, spec);
     }
     return out;
 }
+/**
+ * 读 tty settings 里的 ProxyCommand 闸门（`allowProxyCommand`，默认关）。
+ *
+ * 为什么本包要用 **tty 的**开关而不是自己再加一个：连接簿只有一处（tty），代理命令也只有
+ * 一处能填；两个开关会让「连接簿配了、这个面板不认」变成说不清的状态。代价是本包多依赖一个
+ * 只读 settings 字段——settings 句柄缺失（启动早期）时恒 false，即**关**（失败方向安全）。
+ */
+export function readTtyProxyCommandAllowed(settings) {
+    if (settings === undefined)
+        return false;
+    let raw;
+    try {
+        raw = settings.get('tty');
+    }
+    catch {
+        return false;
+    }
+    if (typeof raw !== 'object' || raw === null)
+        return false;
+    return raw.allowProxyCommand === true;
+}
 /** 从 tty 的 hostKeys 读取已钉扎指纹（作为本插件 TOFU 的种子）。 */
 function readTtyHostKeys(settings) {
     if (settings === undefined)
@@ -583,8 +512,13 @@ export function resolveTarget(target, books) {
              * 但那张卡片管的是 tty 自己的连接簿条目，改不了 docker 目标引用的名字：用户照着找
              * 只会扑空（实测：目标引用 HS-248、连接簿里只有 HS_248_ADMIN，进 tty 卡片什么也改不了）。
              * 真正要改的字段是**本卡片这条目标的「连接簿」下拉**，所以先把这里说清楚，再说备选。
+             *
+             * 末句是给「只能经跳板机 / 代理命令访问」那类情况留的出口（项目级 ROADMAP 第 2 项）：
+             * tty 的 ~/.ssh/config 导入会**自动带上 ProxyJump**、但**永不带上 ProxyCommand**，所以
+             * 后者的条目要么不存在、要么存在却没配代理命令——用户看到「条目不存在」时的第一反应
+             * 是「我明明配过」。
              */
-            return { error: `目标「${target.name}」引用的连接簿条目不存在：${target.book}（在本卡片这条目标的「连接簿」下拉里改选一个已有条目；或把 tty 终端面板的连接簿补一个同名条目；也可清空下拉改为手填 host/username）` };
+            return { error: `目标「${target.name}」引用的连接簿条目不存在：${target.book}（在本卡片这条目标的「连接簿」下拉里改选一个已有条目；或把 tty 终端面板的连接簿补一个同名条目；也可清空下拉改为手填 host/username。若该主机在 ~/.ssh/config 里只配了 ProxyCommand，导入会跳过它——那种条目要在 tty 连接簿里手动建，并打开「允许 ProxyCommand」，见项目级 ROADMAP 第 2 项）` };
         }
         return { resolved: { name: target.name, kind: 'ssh', spec } };
     }
@@ -611,8 +545,47 @@ export function resolveTarget(target, books) {
 const plugin = definePlugin({
     name: 'docker',
     apply(ctx, rawConfig) {
+        /*
+         * 授权来源必须在**第一次 capabilityGranted 之前**绑定（下面的 normalizeConfig 就会查它）：
+         * 环境变量那一半取宿主的启动快照，就地提权那一半取带外授权存储。详见 kit 的 capability.ts /
+         * grant-store.ts。存储每次 apply 新建一个实例 —— 这就是「宿主重启后重新读盘」的语义。
+         *
+         * 落点全部来自 kit 的 `capabilityPaths`（`<DSH home>/dsh-kit/`）：路径只在那里拼一次，
+         * 插件不再自己 join（kit D08：平铺在 DSH 主目录的 `capability-grants.json` / `grant-confirm/`
+         * 不带归属，容易与官方或别的插件撞名）。
+         */
+        const paths = capabilityPaths(dshHome());
+        // **共享实例**（kit D11）：docker 与 tty 同装时各 new 一个会各自缓存一份文件快照，
+        // 后绑定的那个看不到另一个后来写进去的授权（实测：tty 授权成功后自己的快照仍是 false）
+        const grantStore = sharedGrantStore(paths.dir);
+        bindCapabilitySources(ctx, grantStore);
+        /*
+         * 启动期审计：盘上已有的带外授权是**持久**的（重启后直接生效、不再有任何一次确认），所以那次
+         * 「静默继承」必须在日志里留下痕迹——否则「三周前授权的能力今天一开机就开着」无可追溯（kit D09）。
+         * 只报本插件的两条能力；环境变量通道由启动环境本身表达，不在这里重复。
+         *
+         * 刻意放在 `enabled` 判定**之前**：授权是宿主级的、与插件这次是否启用无关；插件这次是禁用态时
+         * 反而更该说一句（「盘上有授权，但插件没开」与「点了没反应」是两回事）。
+         */
+        auditLoadedGrants(grantStore, [CAP_MUTATIONS.env, CAP_EXEC.env], { info: (msg) => ctx.logger.info(msg), warn: (msg) => ctx.logger.warn(msg) }, '[dsh-docker]');
         // volatile 字段解析后是 `{ get() }` 引用，先还原成纯数据（见 @hyzyn/dsh-kit 的 plainConfig）。
         const config = plainConfig((rawConfig ?? {}));
+        /*
+         * 配置里**写着的**能力开关值（**没和授权折叠**）。
+         *
+         * 为什么必须单独留一份：`live.allowMutations` 是「配置值 && 已授权」折叠后的**有效值**，一旦
+         * 用户在没授权时打开过开关，它就成了 false——此后「重算」再拿它当输入，永远回不到 true
+         * （授权到了、工具却不注册，就是那个半个状态）。重算必须从**配置值**出发：
+         *   - `applySection` 把这一份塞回合并结果里（见那里的注释）；
+         *   - 快照里的 `*Configured` 字段也用它，界面靠它把开关画成「开着但未生效」。
+         *
+         * （D141/D142：折叠后的有效值当输入 = 授权到了也回不来；快照缺配置值/来源 = 界面说不出
+         * 「配置开着但没授权」。）
+         */
+        let configuredCapabilities = {
+            allowMutations: config.allowMutations === true,
+            allowExec: config.allowExec === true,
+        };
         let live = normalizeConfig(config);
         if (!live.enabled)
             return;
@@ -677,7 +650,12 @@ const plugin = definePlugin({
                 persistHostKeys(next);
             },
         };
-        const remote = new RemoteExec(logger, hostKeyStore);
+        /*
+         * ProxyCommand 闸门：**每次拨号现读** tty settings（回调只做一次对象属性读取，无 IO）。
+         * 不缓存成布尔值：用户随时可能关掉它，缓存意味着「关了还能用」——这一档最不能出的错。
+         * settingsApi 在 settings 子上下文就绪前是 undefined，那时恒 false（= 关，安全方向）。
+         */
+        const remote = new RemoteExec(logger, hostKeyStore, { proxyCommandAllowed: () => readTtyProxyCommandAllowed(settingsApi) });
         /**
          * 当前生效的 targets：**以 settings 解析值为准**。
          * 为什么不能只读内存里的 live：settings 解析是异步的（服务就绪后才读一次），存在一个
@@ -834,6 +812,29 @@ const plugin = definePlugin({
                 dockerBin: live.dockerBin,
                 allowMutations: live.allowMutations,
                 allowExec: live.allowExec,
+                /*
+                 * 配置里**写着的**值（未与授权折叠）：开关的视觉状态用它，有效值用上面那两个。
+                 * 两张都要给客户端，否则「配置开着但没授权」这个状态在界面上无法表达——那正是本仓最忌讳的
+                 * 「配了没反应」：开关看着是开的、什么都不会发生，却没有任何东西说明原因。
+                 */
+                allowMutationsConfigured: configuredCapabilities.allowMutations,
+                allowExecConfigured: configuredCapabilities.allowExec,
+                // 宿主侧授权（只读）：客户端用它把开关渲染成「点不动 + 说明怎么开」
+                allowMutationsGranted: capabilityGranted(CAP_MUTATIONS),
+                allowExecGranted: capabilityGranted(CAP_EXEC),
+                /*
+                 * 授权来源：'env' = 启动环境变量（界面不给「撤销」按钮，因为它只能靠改启动环境撤销）、
+                 * 'file' = 就地确认写下的带外授权（界面可撤销）、null = 没授权。
+                 * 客户端据此决定显示「撤销宿主授权」还是「去启动环境里去掉它」，两者完全不同。
+                 */
+                allowMutationsGrantSource: capabilityGrantVia(CAP_MUTATIONS) ?? null,
+                allowExecGrantSource: capabilityGrantVia(CAP_EXEC) ?? null,
+                /*
+                 * 授权时刻（Unix 秒；只有 file 通道有值，环境变量通道与未授权都是 null）。授权是**持久**
+                 * 的：重启后它直接生效、不再确认，所以界面至少要能说出「它是什么时候来的」（D09）。
+                 */
+                allowMutationsGrantedAt: capabilityGrantAt(CAP_MUTATIONS) ?? null,
+                allowExecGrantedAt: capabilityGrantAt(CAP_EXEC) ?? null,
                 execTimeoutSec: live.execTimeoutSec,
                 pollIntervalSec: live.pollIntervalSec,
                 logTailDefault: live.logTailDefault,
@@ -1055,8 +1056,14 @@ const plugin = definePlugin({
         };
         const applySection = (section, options) => {
             const before = live;
+            // 能力开关的**配置值**单独记（D141）：section 里没提到它就保持原样（`{}` = 只重算、不改配置）
+            if (section.allowMutations !== undefined)
+                configuredCapabilities.allowMutations = section.allowMutations === true;
+            if (section.allowExec !== undefined)
+                configuredCapabilities.allowExec = section.allowExec === true;
             // hostKeys 只在显式传入时覆盖（避免把 TOFU 运行期新增的记录冲掉）
-            const merged = { ...live, ...section };
+            // 能力两项用**配置值**覆盖折叠后的 live：否则重算的输入就是折叠后的 false（见 configuredCapabilities）
+            const merged = { ...live, ...section, ...configuredCapabilities };
             if (section.hostKeys === undefined)
                 merged.hostKeys = live.hostKeys;
             live = normalizeConfig(merged);
@@ -1087,6 +1094,29 @@ const plugin = definePlugin({
             }
             console.log(`[dsh-docker] config applied (enabled=${String(live.enabled)}, bin=${live.dockerBin}, targets=${String(live.targets.length)}, allowMutations=${String(live.allowMutations)}, allowExec=${String(live.allowExec)})`);
         };
+        /*
+         * 就地提权（见 kit 的 elevation.ts）：页内点开关 → 在宿主上落地一个随机名确认文件 → 授权。
+         *
+         * `onGrantChange` 是这一整段里**最容易漏、也最要紧**的一下：授权到达与撤销都必须重算 live。
+         *   - 授权侧：配置开关可能**早就**是 true（用户先打开过、当时没授权，于是 live.allowMutations
+         *     被折叠成 false），授权到了却不重算，症状就是「开关亮着、工具却没注册」；
+         *   - 撤销侧：不重算会留下「记录没了、工具还开着」，还要收掉在途的写流（D84）。
+         * `applySection({})` 用当前 live 兜底再归一化一次即可（normalizeConfig 会重新问 capabilityGranted）。
+         */
+        const elevation = createElevationManager({
+            confirmDir: paths.confirmDir,
+            store: grantStore,
+            logger,
+            logPrefix: '[dsh-docker]',
+            onGrantChange: () => {
+                applySection({}, { forceRefreshTools: true });
+            },
+        });
+        ctx.effect(() => {
+            return () => {
+                elevation.dispose();
+            };
+        }, 'dsh-docker: elevation cleanup');
         /* ---------- agent 工具 ---------- */
         let toolsApi;
         let toolDisposers = [];
@@ -1299,6 +1329,8 @@ const plugin = definePlugin({
             };
             add('docker_targets', defineTool({
                 name: 'docker_targets',
+                // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                isConcurrencySafe: () => true,
                 description: '列出已配置的 Docker 目标（本机 / SSH 主机），可选探测每个目标的 docker daemon 是否可达。其他 docker_* 工具的 target 参数取自这里。',
                 parameters: { probe: { type: 'boolean', description: 'true 时逐个探测 docker 版本与 daemon 可达性（SSH 目标会建连接，较慢）' } },
                 output: {
@@ -1365,6 +1397,8 @@ const plugin = definePlugin({
             }));
             add('docker_ps', defineTool({
                 name: 'docker_ps',
+                // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                isConcurrencySafe: () => true,
                 description: '列出容器（默认只列运行中的；all:true 含已停止）。**target 传 `*` = 一次列出所有目标**（跨主机，按目标分组返回，单个目标不可达不影响其他目标）。排障第一步。注意：`ports` 为空**不等于**「没暴露端口」——host 网络容器的端口就是宿主机端口、ps 里没有映射，这种情况会给 `net` 字段（如 `net:"host"`），别为此再逐个 docker_inspect。',
                 parameters: {
                     target: { type: 'string', description: '目标名；传 `*` 或省略（仅一个目标时）表示当前目标/全部目标（docker_targets 列出）' },
@@ -1480,6 +1514,8 @@ const plugin = definePlugin({
             }));
             add('docker_attention', defineTool({
                 name: 'docker_attention',
+                // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                isConcurrencySafe: () => true,
                 description: '列出「需要关注」的容器：不健康（unhealthy）/ 反复重启 / 被 OOM 杀 / 非零退出 / 僵死。target 传 `*` 时**跨所有目标聚合**（单目标不可达不影响其他目标）。排障入口：不确定从哪台机器看起时先调它。',
                 parameters: {
                     target: { type: 'string', description: '目标名；传 `*` 表示全部目标（docker_targets 列出）' },
@@ -1622,6 +1658,8 @@ const plugin = definePlugin({
             }));
             add('docker_inspect', defineTool({
                 name: 'docker_inspect',
+                // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                isConcurrencySafe: () => true,
                 description: '读取某个容器的权威详情（docker inspect）：状态/健康检查/退出码/重启次数/端口映射/挂载/网络/启动命令。',
                 parameters: { target: targetParam, id: { type: 'string', required: true, description: '容器名或 ID（来自 docker_ps）' } },
                 output: {
@@ -1676,6 +1714,8 @@ const plugin = definePlugin({
             }));
             add('docker_logs', defineTool({
                 name: 'docker_logs',
+                // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                isConcurrencySafe: () => true,
                 description: '读取某个容器的日志尾部（docker logs --tail）。默认行数取插件配置 logTailDefault（出厂 200）、不带时间戳；可加 timestamps / since。日志可能很大，优先用 tail 而不是全量。',
                 parameters: {
                     target: targetParam,
@@ -1724,6 +1764,8 @@ const plugin = definePlugin({
             }));
             add('docker_stats', defineTool({
                 name: 'docker_stats',
+                // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                isConcurrencySafe: () => true,
                 description: '读取容器实时资源占用（docker stats --no-stream）：CPU%、内存用量/上限、网络与磁盘 IO、PIDs。不传 ids 时返回该目标上全部运行中容器。',
                 parameters: {
                     target: targetParam,
@@ -1794,6 +1836,8 @@ const plugin = definePlugin({
             }));
             add('docker_events', defineTool({
                 name: 'docker_events',
+                // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                isConcurrencySafe: () => true,
                 description: '读取某个目标最近的容器事件（docker events 快照）：start / die / stop / kill / oom / health_status / destroy / rename / update 九类，已过滤掉 exec_* 等噪音。默认看最近 10m。要持续观察请让用户打开面板容器列表的「活动」条。',
                 parameters: {
                     target: targetParam,
@@ -1857,6 +1901,8 @@ const plugin = definePlugin({
             }));
             add('docker_images', defineTool({
                 name: 'docker_images',
+                // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                isConcurrencySafe: () => true,
                 description: '列出某个目标上的镜像（仓库:标签、大小、创建时间、短 ID）。',
                 parameters: { target: targetParam },
                 output: {
@@ -1908,6 +1954,8 @@ const plugin = definePlugin({
             }));
             add('docker_image_inspect', defineTool({
                 name: 'docker_image_inspect',
+                // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                isConcurrencySafe: () => true,
                 description: '读取某个镜像的详情（docker image inspect）与构建历史（docker history）：大小 / 创建时间 / 平台 / 层数与层列表 / 入口与命令 / 暴露端口 / digest / 每步构建命令与大小。',
                 parameters: {
                     target: targetParam,
@@ -1944,6 +1992,8 @@ const plugin = definePlugin({
             }));
             add('docker_networks', defineTool({
                 name: 'docker_networks',
+                // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                isConcurrencySafe: () => true,
                 description: '列出某个目标上的 docker 网络（名称 / 驱动 / 范围 / 是否 internal / 短 ID）。接入的容器列表要进详情页看，不在列表里逐条 inspect。',
                 parameters: { target: targetParam },
                 output: {
@@ -1997,6 +2047,8 @@ const plugin = definePlugin({
             }));
             add('docker_volumes', defineTool({
                 name: 'docker_volumes',
+                // 只读工具：与同轮其它工具并发执行（宿主默认把未声明的工具当独占，见项目级 ROADMAP 第 4 项）
+                isConcurrencySafe: () => true,
                 description: '列出某个目标上的 docker 卷（名称 / 驱动 / 范围 / 挂载点）。',
                 parameters: { target: targetParam },
                 output: {
@@ -2075,7 +2127,7 @@ const plugin = definePlugin({
                     },
                     async execute(args) {
                         if (!live.allowMutations)
-                            throw new Error('变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）');
+                            throw new Error(mutationsOffMessage());
                         const input = (args ?? {});
                         const picked = pickTarget(input.target);
                         if (picked.name === undefined)
@@ -2117,7 +2169,7 @@ const plugin = definePlugin({
                     },
                     async execute(args) {
                         if (!live.allowMutations)
-                            throw new Error('变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）');
+                            throw new Error(mutationsOffMessage());
                         const input = (args ?? {});
                         const picked = pickTarget(input.target);
                         if (picked.name === undefined)
@@ -2151,7 +2203,7 @@ const plugin = definePlugin({
                     },
                     async execute(args) {
                         if (!live.allowMutations)
-                            throw new Error('变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）');
+                            throw new Error(mutationsOffMessage());
                         const input = (args ?? {});
                         const picked = pickTarget(input.target);
                         if (picked.name === undefined)
@@ -2191,7 +2243,7 @@ const plugin = definePlugin({
                     },
                     async execute(args) {
                         if (!live.allowMutations)
-                            throw new Error('变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）');
+                            throw new Error(mutationsOffMessage());
                         const input = (args ?? {});
                         const picked = pickTarget(input.target);
                         if (picked.name === undefined)
@@ -2250,7 +2302,7 @@ const plugin = definePlugin({
                     },
                     async execute(args) {
                         if (!live.allowExec)
-                            throw new Error('exec 未启用（插件配置 → Docker 容器面板 → 允许 exec）');
+                            throw new Error(execOffMessage());
                         const input = (args ?? {});
                         const picked = pickTarget(input.target);
                         if (picked.name === undefined)
@@ -2590,7 +2642,7 @@ const plugin = definePlugin({
          */
         const servePullStream = async (req, res, params) => {
             if (!live.allowMutations) {
-                writeJson(res, 403, { error: '变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）' });
+                writeJson(res, 403, { error: mutationsOffMessage() });
                 return;
             }
             const picked = pickTarget(params.get('target'));
@@ -2638,7 +2690,7 @@ const plugin = definePlugin({
                     kind: 'prefix',
                     path: ROUTE_PREFIX,
                     handler: async (req, res) => {
-                        const loopback = isLoopbackHttp(req);
+                        const loopback = isLoopbackRequestStrict(req);
                         // 字面量环回同步判定（保持「第一拍就建流」的时序）；仅别名主机名才等 DNS
                         if (loopback instanceof Promise) {
                             if (!(await loopback)) {
@@ -2651,10 +2703,11 @@ const plugin = definePlugin({
                             return;
                         }
                         const sub = new URL(req.url ?? '/', 'http://loopback').pathname.slice(ROUTE_PREFIX.length);
-                        // 插件禁用时只保留 /config 读写：设置卡片靠它渲染，也是重新启用插件的唯一
-                        // UI 入口（不能一并关掉，否则卡片消失就没有恢复路径了）；其余数据路由一律
-                        // 403——agent 工具已由 refreshTools 同步清空，这里只管 HTTP 半体。
-                        if (!live.enabled && sub !== '/config') {
+                        // 插件禁用时只保留 /config 读写与 /elevate 族：设置卡片靠前者渲染，也是重新启用插件的
+                        // 唯一 UI 入口（不能一并关掉，否则卡片消失就没有恢复路径了）；授权的宿主级操作也不该
+                        // 因为插件被停用而失效（用户先授权再启用插件同样合理）。其余数据路由一律 403——
+                        // agent 工具已由 refreshTools 同步清空，这里只管 HTTP 半体。
+                        if (!live.enabled && sub !== '/config' && !sub.startsWith('/elevate')) {
                             writeJson(res, 403, { error: '插件已禁用（插件配置 → Docker 容器面板 → 启用插件）' });
                             return;
                         }
@@ -2683,6 +2736,18 @@ const plugin = definePlugin({
                                     continue;
                                 patch[key] = body[key];
                             }
+                            /*
+                             * **能力开关不能凭空升**：提权只认宿主侧来源（启动环境变量，或带外确认写下的授权）。
+                             * HTTP 侧给 true 而没有授权一律驳回并说清两条路。这不是「输入不合法」而是「没获授权」——
+                             * 文案必须给出**怎么授权**，否则用户会对着一个点不动的开关反复点。
+                             * 校验放在**落盘之前**（与下面那条 normalizeConfig 干跑同一口径）：错误路径不留脏配置。
+                             */
+                            for (const [key, spec] of [['allowMutations', CAP_MUTATIONS], ['allowExec', CAP_EXEC]]) {
+                                if (patch[key] === true && !capabilityGranted(spec)) {
+                                    writeJson(res, 400, { error: capabilityDeniedMessage(spec, { inPlace: true }) });
+                                    return;
+                                }
+                            }
                             // 空 targets 只在显式 clearTargets 时才允许清空：卡片若因启动竞态拿到
                             // 空列表，保存不会再把已配置的目标抹掉（防数据丢失）
                             if (Array.isArray(patch.targets) && patch.targets.length === 0 && body.clearTargets !== true) {
@@ -2855,6 +2920,42 @@ const plugin = definePlugin({
                             writeJson(res, 400, { error: 'invalid JSON body' });
                             return;
                         }
+                        /*
+                         * 就地提权（三条子路由）。放在这里而不是 `/config` 旁边是有原因的：**同源证明由上面那段
+                         * MUTATION_SUBROUTES 判据提供**，而它只覆盖它后面这段分发——写在它前面就是裸的了
+                         * （跨站页面能撤销授权、能反复试确认）。三条都做成 POST 也是为了复用那一条判据
+                         * （它只认 POST；`status` 做成 GET 会绕过）。
+                         */
+                        if (sub === '/elevate' || sub === '/elevate/status' || sub === '/elevate/revoke') {
+                            const capability = typeof body.capability === 'string' ? body.capability : '';
+                            const spec = CAPABILITIES.get(capability);
+                            if (spec === undefined) {
+                                writeJson(res, 400, { error: `未知能力开关: ${capability === '' ? '(空)' : capability}（可用：${[...CAPABILITIES.keys()].join(' / ')}）` });
+                                return;
+                            }
+                            if (sub === '/elevate/status') {
+                                writeJson(res, 200, elevation.status(spec.env));
+                                return;
+                            }
+                            if (sub === '/elevate/revoke') {
+                                // 降权零门槛：不要求任何确认（紧急刹车不等重启）。撤销带来的重算由 elevation 的
+                                // onGrantChange 回调负责（不变量 6），这里不再补一刀。
+                                const revoked = elevation.revoke(spec.env);
+                                writeJson(res, 200, { ok: true, revoked, config: snapshot() });
+                                return;
+                            }
+                            const result = elevation.begin(spec.env);
+                            if (result.status === 'rate-limited') {
+                                writeJson(res, 429, { ...result, error: '短时间内发起太多次，请稍后再试' });
+                                return;
+                            }
+                            if (result.status === 'error') {
+                                writeJson(res, 500, result);
+                                return;
+                            }
+                            writeJson(res, 200, result);
+                            return;
+                        }
                         // 跨目标聚合（0.15.0）：target='*' 不是目标名，必须在 pickTarget 之前分流，
                         // 否则会被当成「未知目标」直接 400
                         const wantsAllTargets = typeof body.target === 'string' && body.target.trim() === '*';
@@ -2978,7 +3079,7 @@ const plugin = definePlugin({
                                 }
                                 case '/images/remove': {
                                     if (!live.allowMutations) {
-                                        writeJson(res, 403, { error: '变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）' });
+                                        writeJson(res, 403, { error: mutationsOffMessage() });
                                         return;
                                     }
                                     if (typeof body.ref !== 'string' || body.ref.trim() === '') {
@@ -2990,7 +3091,7 @@ const plugin = definePlugin({
                                 }
                                 case '/images/prune': {
                                     if (!live.allowMutations) {
-                                        writeJson(res, 403, { error: '变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）' });
+                                        writeJson(res, 403, { error: mutationsOffMessage() });
                                         return;
                                     }
                                     writeJson(res, 200, { ok: true, result: await api.imagePrune() });
@@ -3010,7 +3111,7 @@ const plugin = definePlugin({
                                 }
                                 case '/networks/remove': {
                                     if (!live.allowMutations) {
-                                        writeJson(res, 403, { error: '变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）' });
+                                        writeJson(res, 403, { error: mutationsOffMessage() });
                                         return;
                                     }
                                     if (typeof body.name !== 'string' || body.name.trim() === '') {
@@ -3022,7 +3123,7 @@ const plugin = definePlugin({
                                 }
                                 case '/networks/prune': {
                                     if (!live.allowMutations) {
-                                        writeJson(res, 403, { error: '变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）' });
+                                        writeJson(res, 403, { error: mutationsOffMessage() });
                                         return;
                                     }
                                     writeJson(res, 200, { ok: true, result: await api.networkPrune() });
@@ -3042,7 +3143,7 @@ const plugin = definePlugin({
                                 }
                                 case '/volumes/remove': {
                                     if (!live.allowMutations) {
-                                        writeJson(res, 403, { error: '变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）' });
+                                        writeJson(res, 403, { error: mutationsOffMessage() });
                                         return;
                                     }
                                     if (typeof body.name !== 'string' || body.name.trim() === '') {
@@ -3054,7 +3155,7 @@ const plugin = definePlugin({
                                 }
                                 case '/volumes/prune': {
                                     if (!live.allowMutations) {
-                                        writeJson(res, 403, { error: '变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）' });
+                                        writeJson(res, 403, { error: mutationsOffMessage() });
                                         return;
                                     }
                                     writeJson(res, 200, { ok: true, result: await api.volumePrune() });
@@ -3062,7 +3163,7 @@ const plugin = definePlugin({
                                 }
                                 case '/action': {
                                     if (!live.allowMutations) {
-                                        writeJson(res, 403, { error: '变更操作未启用（插件配置 → Docker 容器面板 → 允许变更操作）' });
+                                        writeJson(res, 403, { error: mutationsOffMessage() });
                                         return;
                                     }
                                     if (typeof body.id !== 'string') {
@@ -3079,7 +3180,7 @@ const plugin = definePlugin({
                                 }
                                 case '/exec': {
                                     if (!live.allowExec) {
-                                        writeJson(res, 403, { error: 'exec 未启用（插件配置 → Docker 容器面板 → 允许 exec）' });
+                                        writeJson(res, 403, { error: execOffMessage() });
                                         return;
                                     }
                                     if (typeof body.id !== 'string' || typeof body.command !== 'string') {
@@ -3124,10 +3225,13 @@ const plugin = definePlugin({
                 const offAutoPage = suppressAutoSettingsPage(settingsCtx, ctx);
                 settingsScope = scope;
                 settingsApi = { get: (ns) => readSettingsEntry(settingsCtx, ns) };
-                // 立刻读一次 resolved 值（schema 默认值 ← composition base ← 用户层）
+                // 立刻读一次 resolved 值（schema 默认值 ← composition base ← 用户层）。
+                // 走 applySection 而不是直接 normalizeConfig：能力开关的**配置值**要一起记下来（见
+                // configuredCapabilities），否则此后的就地提权重算会拿折叠后的 false 当输入。
                 const resolved = scope.get();
-                if (typeof resolved === 'object' && resolved !== null)
-                    live = normalizeConfig(resolved);
+                if (typeof resolved === 'object' && resolved !== null) {
+                    applySection(resolved, { forceRefreshTools: true });
+                }
                 const diag = (resolved ?? {});
                 console.log(`[dsh-docker] settings resolved (keys=${Object.keys(diag).join('|')}, targets=${Array.isArray(diag.targets) ? String(diag.targets.length) : 'not-array'}, hostKeys=${Array.isArray(diag.hostKeys) ? String(diag.hostKeys.length) : 'not-array'})`);
                 refreshTools();