rdsh-gateway 0.9.0 → 0.11.0

package/dist/join.js

@@ -22,6 +22,23 @@ import { acquireJoinLock, releaseJoinLock } from "./lock.js";
 import { responderHandshake, Aead } from "./e2ee.js";
 import { loadOrCreateE2eeKeyPair } from "./e2ee-key-store.js";
 import { GATE_COOKIE, signGateCookie, verifyGateCookie, verifyGateCode } from "./access-gate.js";
+import { startDirect, directBootstrapScript } from "./direct.js";
+import { createDirectTicketManager } from "./direct-ticket.js";
+import { loadOrCreateDirectSecret } from "./direct-secret.js";
+import { RDSH_WEBVIEW_API, injectHtmlScript } from "./rdsh-webview-api.js";
+/**
+ * 页面授权脚本（plain 与 raw 两条 inner dispatcher 共用，禁止各写一份）：
+ * 直连 bootstrap + （设了口令时）raw 门禁解锁 token。
+ *
+ * 为什么 raw 通道也**必须**注入：raw（E2EE）流按设计不向 host 转发任何 cookie，
+ * 页面只能靠这段脚本带 token 请求 `/__rdsh/authorize` 才能把 rawAuthorized 置真；
+ * 漏注入 ⇒ raw 门禁（accessCode 非空时为 fail-closed）永远无法满足 ⇒ 经 E2EE 的
+ * 客户端每个请求都被 CLOSE 403、表现为"一直 connecting"。
+ * （24-direct-first 首版只在 plain 注入，E2EE 客户端因此被锁死；本函数即该回归的单一来源。）
+ */
+export function pageAuthorizeScript(accessCode) {
+    return directBootstrapScript(accessCode === null ? null : signGateCookie(accessCode).value);
+}
 /** 判断错误是否为 TLS 证书类错误（自签/过期/域名不匹配）。 */
 function isCertError(err) {
     const code = err?.code ?? "";
@@ -157,6 +174,12 @@ export function isJsContentType(headers) {
     const s = Array.isArray(ct) ? ct.join(";") : (ct ?? "");
     return /javascript/i.test(s);
 }
+/** HTML 响应判定（content-type 含 text/html）。 */
+export function isHtmlContentType(headers) {
+    const ct = headers["content-type"];
+    const s = Array.isArray(ct) ? ct.join(";") : (ct ?? "");
+    return /text\/html/i.test(s);
+}
 /**
  * 最小 patch：把 DSH 客户端 bundle 里的前端 isLoopback 判定替换为 true
  * （持久设置/API key 输入只对 loopback 开放；E2EE 流上信任基础等同 loopback）。
@@ -250,6 +273,10 @@ export function startJoin(opts) {
     const uiCompat = { trustE2EEAsLoopback: opts.dshUiCompat?.trustE2EEAsLoopback !== false };
     // 访问口令（feature 15）：可变引用 → setAccessCode 运行中切换；null = gate off
     const gate = { accessCode: opts.gateway?.accessCode ?? null };
+    // raw 门禁 + 候选（24-direct-first）：提供 direct 回调即启用候选端点；raw 门禁（authorize）仅设口令时生效
+    const rawGate = opts.direct !== undefined
+        ? { candidates: opts.direct.candidates, mintTicket: opts.direct.mintTicket }
+        : undefined;
     const hostName = opts.name ?? "本主机";
     const gateFailures = { count: 0, lockedUntil: 0 };
     const log = (level, message) => {
@@ -309,6 +336,10 @@ export function startJoin(opts) {
          * 键含 query 且不截断：combo 路由用 query 选内容，资源 URL 由内容决定（rev/hash），内容一变 URL 就变。
          */
         const patchSkipped = new Set();
+        /** rdsh WebView API 是否已注入过（每个进程只打一次日志，避免页面加载刷屏）。 */
+        let adapterInjectionLogged = false;
+        /** raw 门禁：当前 raw 流是否已被页面授权（动态判定：见 handleOpen 的条件，含运行中 gate 开关） */
+        let rawAuthorized = false;
         /** 从转发头里取 rdsh_gate cookie（hub D12 白名单透传）。 */
         function gateCookie(headers) {
             const ck = headers["cookie"];
@@ -335,11 +366,11 @@ export function startJoin(opts) {
             const html = gateChallengeHtml(hostName, path, error, acceptLanguage);
             sendSyntheticHttp(send, streamId, 200, { "content-type": "text/html; charset=utf-8" }, Buffer.from(html));
         }
-        /** 校验 code 提交（POST gate_code）→ 302 回跳 + 发 cookie，或回 challenge 错误。 */
+        /** 校验 code 提交（POST gate_code）→ 303 回跳 + 发 cookie，或回 challenge 错误。 */
         function handleGateSubmit(streamId, state) {
             const code = gate.accessCode;
             if (code === null) {
-                sendSyntheticHttp(send, streamId, 302, { location: state.path }, Buffer.alloc(0));
+                sendSyntheticHttp(send, streamId, 303, { location: state.path }, Buffer.alloc(0));
                 return;
             }
             if (gateBlocked()) {
@@ -358,7 +389,7 @@ export function startJoin(opts) {
             if (input !== null && verifyGateCode(input, code)) {
                 gateFailures.count = 0;
                 const { value } = signGateCookie(code);
-                sendSyntheticHttp(send, streamId, 302, { location: state.path, "set-cookie": `${GATE_COOKIE}=${value}; HttpOnly; SameSite=Lax; Path=/; Max-Age=${7 * 24 * 3600}` }, Buffer.alloc(0));
+                sendSyntheticHttp(send, streamId, 303, { location: state.path, "set-cookie": `${GATE_COOKIE}=${value}; HttpOnly; SameSite=Lax; Path=/; Max-Age=${7 * 24 * 3600}` }, Buffer.alloc(0));
             }
             else {
                 gateFailures.count += 1;
@@ -439,6 +470,28 @@ export function startJoin(opts) {
                 send(encodeFrame(FRAME_TYPE.ERROR, frame.streamId, jsonPayload({ code: "BAD_OPEN", message: "malformed open" })));
                 return;
             }
+            // ---- raw 门禁 + 候选端点（仅 raw inner dispatcher：dio.rawGate 定义时）----
+            if (dio?.rawGate !== undefined) {
+                // raw 门禁（仅设口令时）：授权前只接受 authorize 请求，否则 fail-closed 关流（修 raw 绕过，R7）
+                if (gate.accessCode !== null && !rawAuthorized) {
+                    if (path.startsWith("/__rdsh/authorize")) {
+                        const token = new URL(path, "http://rdsh.local").searchParams.get("token") ?? "";
+                        if (token !== "" && verifyGateCookie(gate.accessCode, token)) {
+                            rawAuthorized = true;
+                            sendSyntheticHttp(send, frame.streamId, 204, {}, Buffer.alloc(0));
+                            return;
+                        }
+                    }
+                    send(encodeFrame(FRAME_TYPE.CLOSE, frame.streamId, jsonPayload({ code: 403, message: "raw stream not authorized" })));
+                    return;
+                }
+                // 候选 + 一次性直连票（无论是否设口令都提供；经 E2EE，hub 不可见，R3/R4）
+                if (path === "/__rdsh/direct-candidates" || path.startsWith("/__rdsh/direct-candidates?")) {
+                    const body = Buffer.from(JSON.stringify({ candidates: dio.rawGate.candidates(), ticket: dio.rawGate.mintTicket() }));
+                    sendSyntheticHttp(send, frame.streamId, 200, { "content-type": "application/json" }, body);
+                    return;
+                }
+            }
             // ---- 访问口令 gate（仅 plain dispatcher：dio.gate=true 且已设 accessCode）----
             if (dio?.gate === true && gate.accessCode !== null) {
                 const code = gate.accessCode;
@@ -484,6 +537,34 @@ export function startJoin(opts) {
                 const baseHeaders = normalizeRespHeaders(upRes.headers);
                 // 已确认该 URL 不含目标串（DSH 前端壳资源就属此类）→ 直接流式，省掉白解压与全量扫描
                 const wantsPatch = dio?.jsPatch?.() === true && isJsContentType(upRes.headers) && !patchSkipped.has(path);
+                const wantsInject = dio?.htmlInject !== undefined && isHtmlContentType(upRes.headers) && upRes.headers["content-encoding"] === undefined;
+                // HTML + 注入：缓冲后注入（htmlInject 会改 body 长度，须先处理再发 OPEN 并重算 content-length）
+                if (wantsInject) {
+                    const htmlChunks = [];
+                    upRes.on("data", (chunk) => htmlChunks.push(chunk));
+                    upRes.on("end", () => {
+                        const inject = typeof dio.htmlInject === "function" ? dio.htmlInject() : dio.htmlInject;
+                        const html = injectHtmlScript(Buffer.concat(htmlChunks).toString("utf8"), inject);
+                        const outHeaders = {
+                            ...baseHeaders,
+                            "content-length": String(Buffer.byteLength(html)),
+                        };
+                        delete outHeaders["transfer-encoding"];
+                        if (!adapterInjectionLogged) {
+                            adapterInjectionLogged = true;
+                            console.log("[rdsh] rdsh webview api injected (window.__rdshWebViewApi v1)");
+                        }
+                        send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({ kind: "http", status, reason: upRes.statusMessage, headers: outHeaders })));
+                        sendChunkedBody(send, streamId, Buffer.from(html));
+                        send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 0 })));
+                        httpStreams.delete(streamId);
+                    });
+                    upRes.on("error", () => {
+                        send(encodeFrame(FRAME_TYPE.CLOSE, streamId, jsonPayload({ code: 502, message: "upstream error" })));
+                        httpStreams.delete(streamId);
+                    });
+                    return;
+                }
                 // 非 JS / 未开补丁：保持原流式路径（OPEN 立即发，body 边到边发）
                 if (!wantsPatch) {
                     send(encodeFrame(FRAME_TYPE.OPEN, streamId, jsonPayload({ kind: "http", status, reason: upRes.statusMessage, headers: baseHeaders })));
@@ -636,7 +717,14 @@ export function startJoin(opts) {
         }
         return { handleFrame, cleanup };
     }
-    const plainDispatcher = makeInnerDispatcher(sendTunnelFrame, { jsPatch: () => uiCompat.trustE2EEAsLoopback, gate: true });
+    const plainDispatcher = makeInnerDispatcher(sendTunnelFrame, {
+        jsPatch: () => uiCompat.trustE2EEAsLoopback,
+        gate: true,
+        htmlInject: () => {
+            // 直连 bootstrap 始终注入（join 模式）；页面授权 token 仅设口令时生成（无口令则跳过 raw 授权、只取候选）
+            return RDSH_WEBVIEW_API + pageAuthorizeScript(gate.accessCode);
+        },
+    });
     // host 端 E2EE 静态密钥对（持久化 ~/.rdsh/e2ee-key.json；join 注册时上送指纹）
     let hostE2eeKeypair;
     try {
@@ -668,7 +756,13 @@ export function startJoin(opts) {
                 // 最后一道：任何加密/封帧异常只记录，绝不重抛打死 host
                 console.error(`[join] e2ee send failed: ${err instanceof Error ? err.message : String(err)}`);
             }
-        }, { jsPatch: () => uiCompat.trustE2EEAsLoopback });
+        }, {
+            jsPatch: () => uiCompat.trustE2EEAsLoopback,
+            rawGate,
+            // raw 门禁的解锁脚本：与 plain 同一来源（pageAuthorizeScript）。
+            // raw 流不转发 cookie，这里是页面唯一的授权入口；缺了它 raw 门禁必然 fail-closed。
+            htmlInject: () => pageAuthorizeScript(gate.accessCode),
+        });
         rawStreams.set(streamId, {
             handshakeBuf: Buffer.alloc(0),
             keys: null,
@@ -934,6 +1028,12 @@ export async function join(opts) {
     const { token, insecure, name } = await registerJoin(opts);
     console.log(`rdsh join: dsh web on 127.0.0.1:${dsh.port}`);
     console.log(`rdsh join: connecting to ${opts.hubUrl}...`);
+    const accessCode = opts.gateway?.accessCode ?? null;
+    // 直连密钥（per-host 随机，自动生成）+ 一次性直连票管理器（R4）：密钥独立于口令（方案 B）
+    const directSecret = loadOrCreateDirectSecret();
+    const ticketManager = createDirectTicketManager(directSecret);
+    // 直连口句柄引用（candidates 回调在 startJoin 内被调用；直连口稍后才启动，故用可变引用）
+    let directHandle;
     const handle = startJoin({
         hubUrl: opts.hubUrl,
         token,
@@ -942,6 +1042,9 @@ export async function join(opts) {
         role: "cli",
         dshUiCompat: opts.dshUiCompat,
         gateway: opts.gateway,
+        direct: opts.direct !== undefined
+            ? { candidates: () => directHandle?.candidates() ?? [], mintTicket: () => ticketManager.mint() }
+            : undefined,
         dshAuthCookieHeader,
         name,
         hooks: {
@@ -955,6 +1058,27 @@ export async function join(opts) {
             },
         },
     });
+    // 直连口（24-direct-first，方案 B）：join 模式**始终监听**，门禁 = ticket（可选口令为增强层）
+    if (opts.direct !== undefined) {
+        try {
+            directHandle = await startDirect({
+                dshPort: dsh.port,
+                dshAuthCookieHeader,
+                secret: directSecret,
+                accessCode,
+                consumeTicket: (t) => ticketManager.consume(t),
+                host: opts.direct.host,
+                port: opts.direct.port,
+                dshUiCompat: { trustPairedAsLoopback: opts.dshUiCompat?.trustE2EEAsLoopback !== false },
+            });
+            const cands = directHandle.candidates();
+            console.log(`rdsh join: direct on :${directHandle.actualPort}（${accessCode === null ? "ticket 门禁" : "ticket + 口令门禁"}）—— ${cands.map((c) => `http://${c.host}:${c.port}`).join(", ") || "(无内网网卡)"}`);
+        }
+        catch (err) {
+            // 直连口监听失败（端口占用等）不阻断隧道：隧道照常，仅直连不可用
+            console.error(`rdsh join: direct listener failed to start: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     let shuttingDown = false;
     const shutdown = async (signal, code = 0) => {
         if (shuttingDown)
@@ -962,6 +1086,8 @@ export async function join(opts) {
         shuttingDown = true;
         if (signal !== "")
             console.log(`\nrdsh: received ${signal}, shutting down...`);
+        if (directHandle !== undefined)
+            await directHandle.stop().catch(() => undefined);
         await handle.stop();
         await dsh.stop();
         process.exit(code);

package/dist/rdsh-webview-api.d.ts

@@ -0,0 +1,17 @@
+/**
+ * rdsh-webview-api.ts — 智能体 API 契约适配脚本（注入 DSH 首页，feature 22）。
+ *
+ * 挂出稳定契约 `window.__rdshWebViewApi`（version 1），供 WebView 客户端（如 garsync App）优先消费，
+ * 以把「DSH 版本适配」从 App（发版慢）挪到 gateway（随 npm 包快速发布）。
+ *
+ * 契约正文与语义以 garsync `doc/feature/108_agent_api_contract/req.md` R7 为准；
+ * 本脚本是 garsync `lib/rdsh/rdsh_web_bridge.dart` 的 `_bridgeJs` 的**精简等价物**：
+ * - 保留：isDshPage / readReply / fillAndSend 三方法及其 DOM 细节（Lexical 写入管线、
+ *   键盘守卫、最后一轮答案提取、UTF-8 安全 base64）；
+ * - 去掉：`report()` 通道与 105 诊断探针（那是 App 侧独有的 debug 机制）。
+ *
+ * 安全约定：幂等（已注入即返回）、防御式（任何 DOM 缺失/异常返回安全默认值、绝不抛错）。
+ */
+export declare const RDSH_WEBVIEW_API = "(function () {\n  if (window.__rdshWebViewApi) return;\n  function findComposer() {\n    var el = document.querySelector('[data-lexical-editor=\"true\"]');\n    if (el) return { el: el, kind: 'lexical' };\n    el = document.querySelector('[contenteditable=\"true\"]');\n    if (el) return { el: el, kind: 'contenteditable' };\n    el = document.querySelector('textarea');\n    if (el) return { el: el, kind: 'textarea' };\n    return null;\n  }\n  function selectAll(el) {\n    var tag = el.tagName;\n    if (tag === 'TEXTAREA' || tag === 'INPUT') { el.select(); return; }\n    var range = document.createRange();\n    range.selectNodeContents(el);\n    var sel = window.getSelection();\n    sel.removeAllRanges();\n    sel.addRange(range);\n  }\n  function insertText(el, text) {\n    el.focus();\n    try { selectAll(el); } catch (e) {}\n    // 1) execCommand \u8D70\u6D4F\u89C8\u5668\u7F16\u8F91\u7BA1\u7EBF\uFF0C\u8BA9 Lexical \u6536\u5230 input \u4E8B\u4EF6\u3002\n    try { if (document.execCommand('insertText', false, text)) return true; } catch (e) {}\n    // 2) \u663E\u5F0F beforeinput\u3002\n    try {\n      el.dispatchEvent(new InputEvent('beforeinput', { inputType: 'insertText', data: text, bubbles: true, cancelable: true }));\n      return true;\n    } catch (e) {}\n    // 3) \u515C\u5E95\uFF1A\u76F4\u63A5\u5199 DOM + \u89E6\u53D1 input\u3002\n    try {\n      var tag = el.tagName;\n      if (tag === 'TEXTAREA' || tag === 'INPUT') {\n        var proto = tag === 'TEXTAREA' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;\n        Object.getOwnPropertyDescriptor(proto, 'value').set.call(el, text);\n      } else {\n        el.textContent = text;\n      }\n      el.dispatchEvent(new Event('input', { bubbles: true }));\n      return true;\n    } catch (e) {}\n    return false;\n  }\n  function pressEnter(el) {\n    var opts = { key: 'Enter', code: 'Enter', keyCode: 13, which: 13, bubbles: true, cancelable: true, composed: true, isComposing: false };\n    try {\n      el.dispatchEvent(new KeyboardEvent('keydown', opts));\n      el.dispatchEvent(new KeyboardEvent('keypress', opts));\n      el.dispatchEvent(new KeyboardEvent('keyup', opts));\n    } catch (e) {}\n  }\n  // \u952E\u76D8\u5B88\u536B\uFF1A\u8BED\u97F3\u5199\u5165\u540E\u5173\u8F6F\u952E\u76D8\uFF1B\u7528\u6237\u771F\u5B9E\u89E6\u6478\u9875\u9762\u5373\u89E3\u9664\u3002\n  var keyboardGuard = false;\n  function dismissKeyboard() {\n    try {\n      var active = document.activeElement;\n      if (active && active !== document.body && typeof active.blur === 'function') active.blur();\n      var selection = window.getSelection();\n      if (selection && selection.removeAllRanges) selection.removeAllRanges();\n    } catch (e) {}\n  }\n  function onUserTouch() { if (keyboardGuard) keyboardGuard = false; }\n  document.addEventListener('focusin', function () { if (!keyboardGuard) return; dismissKeyboard(); }, true);\n  document.addEventListener('pointerdown', onUserTouch, true);\n  document.addEventListener('touchstart', onUserTouch, true);\n\n  // \u5355\u4E2A flow \u8282\u70B9\u7684\u53EF\u89C1\u6587\u672C\uFF1BproseOnly \u989D\u5916\u4E22\u5F03\u6574\u5757\u4EE3\u7801\u4E0E\u8868\u683C\uFF08105 \u53EA\u8BFB\u7B54\u6848\u6B63\u6587\uFF09\u3002\n  function answerTextOf(el, proseOnly) {\n    var clone = el.cloneNode(true);\n    var selector = '[data-variant=\"think\"],[data-variant=\"others\"]';\n    if (proseOnly) selector += ',pre,table';\n    var drop = clone.querySelectorAll(selector);\n    for (var i = 0; i < drop.length; i++) { if (drop[i].parentNode) drop[i].parentNode.removeChild(drop[i]); }\n    return (clone.innerText || clone.textContent || '').trim();\n  }\n  // \u67D0\u4E2A flow kind \u7684\u6700\u5927 turn\uFF08\u53D6\u4E0D\u5230 = -1\uFF09\u3002\n  // 111\uFF1AApp \u7528 turn / userTurn \u5224\u65AD\"\u7528\u6237\u662F\u5426\u53D1\u4E86\u65B0\u6D88\u606F\"\uFF0C\u4ECE\u800C\u7ACB\u5373\u505C\u6B62\u6717\u8BFB\u3002\n  function maxTurnOf(kind) {\n    var nodes = document.querySelectorAll('[data-chat-flow-kind=\"' + kind + '\"]');\n    var max = -1;\n    for (var i = 0; i < nodes.length; i++) {\n      var t = parseInt(nodes[i].getAttribute('data-chat-turn'), 10);\n      if (!isNaN(t) && t > max) max = t;\n    }\n    return max;\n  }\n  // \u6700\u540E\u4E00\u8F6E\u7684\u7B54\u6848\u90E8\u5206\uFF08\u6392\u9664 reasoning\uFF0C\u53D6\u6700\u5927 turn\uFF0C\u9010 part \u62FC\u63A5\uFF09\u3002\n  // \u8FD4\u56DE { text, turn }\uFF1Aturn \u4E0E\u8BE5\u8F6E\u7B54\u6848\u5BF9\u5E94\uFF0C\u4F9B readReply \u56DE\u5E26\u7ED9 App\u3002\n  function latestAnswer() {\n    var steps = Array.prototype.slice.call(document.querySelectorAll('[data-chat-flow-kind=\"assistant-step\"]'));\n    var answers = steps.filter(function (el) { return el.getAttribute('data-chat-group-part') !== 'reasoning'; });\n    var maxTurn = -1;\n    for (var i = 0; i < answers.length; i++) {\n      var turn = parseInt(answers[i].getAttribute('data-chat-turn'), 10);\n      if (!isNaN(turn) && turn > maxTurn) maxTurn = turn;\n    }\n    var parts = answers.filter(function (el) { return parseInt(el.getAttribute('data-chat-turn'), 10) === maxTurn; });\n    var texts = [];\n    for (var j = 0; j < parts.length; j++) {\n      var text = answerTextOf(parts[j], true);\n      if (text.length) texts.push(text);\n    }\n    return { text: texts.join('\\n\\n'), turn: maxTurn };\n  }\n\n  window.__rdshWebViewApi = {\n    version: 1,\n    // 104\uFF1A\u5199\u5165 composer \u5E76\u63D0\u4EA4\u3002\u8FD4\u56DE\u88F8\u72B6\u6001 token\u3002\n    fillAndSend: function (text) {\n      var found = findComposer();\n      if (!found) return 'no-composer';\n      keyboardGuard = false;\n      if (!insertText(found.el, text)) return 'fill-failed';\n      keyboardGuard = true;\n      dismissKeyboard();\n      setTimeout(function () { pressEnter(found.el); dismissKeyboard(); }, 80);\n      return 'ok';\n    },\n    // 105/111\uFF1A\u5F85\u6717\u8BFB\u5185\u5BB9 + \u72B6\u6001\u3002\u8FD4\u56DE UTF-8 \u5B89\u5168\u7684 base64 JSON\n    // {dsh, streaming, text, turn, userTurn}\uFF08turn / userTurn \u53D6\u4E0D\u5230\u65F6\u4E3A -1\uFF09\u3002\n    readReply: function () {\n      var out = { dsh: false, streaming: 0, text: '', turn: -1, userTurn: -1 };\n      try {\n        out.streaming = document.querySelectorAll('[data-streaming]').length;\n        if (document.querySelectorAll('[data-chat-flow-kind]').length > 0) {\n          out.dsh = true;\n          var answer = latestAnswer();\n          out.text = answer.text;\n          out.turn = answer.turn;\n          out.userTurn = maxTurnOf('user');\n        } else {\n          out.text = document.body ? document.body.innerText : '';\n        }\n      } catch (e) {}\n      return window.btoa(unescape(encodeURIComponent(JSON.stringify(out))));\n    },\n    // 107\uFF1A\u662F\u5426 DSH \u4F1A\u8BDD\u9875\uFF08\u8F7B\u91CF\u5224\u5B9A\uFF0C\u53EF\u8F6E\u8BE2\uFF09\u3002\u8FD4\u56DE\u88F8 '1' / '0'\u3002\n    isDshPage: function () {\n      try {\n        return document.querySelectorAll('[data-chat-flow-kind]').length > 0 ? '1' : '0';\n      } catch (e) { return '0'; }\n    }\n  };\n})();";
+/** 把 `<script>${script}</script>` 插到 `</head>` 前（无则前置）；纯函数，可单测。 */
+export declare function injectHtmlScript(html: string, script: string): string;

package/dist/rdsh-webview-api.js

@@ -0,0 +1,167 @@
+/**
+ * rdsh-webview-api.ts — 智能体 API 契约适配脚本（注入 DSH 首页，feature 22）。
+ *
+ * 挂出稳定契约 `window.__rdshWebViewApi`（version 1），供 WebView 客户端（如 garsync App）优先消费，
+ * 以把「DSH 版本适配」从 App（发版慢）挪到 gateway（随 npm 包快速发布）。
+ *
+ * 契约正文与语义以 garsync `doc/feature/108_agent_api_contract/req.md` R7 为准；
+ * 本脚本是 garsync `lib/rdsh/rdsh_web_bridge.dart` 的 `_bridgeJs` 的**精简等价物**：
+ * - 保留：isDshPage / readReply / fillAndSend 三方法及其 DOM 细节（Lexical 写入管线、
+ *   键盘守卫、最后一轮答案提取、UTF-8 安全 base64）；
+ * - 去掉：`report()` 通道与 105 诊断探针（那是 App 侧独有的 debug 机制）。
+ *
+ * 安全约定：幂等（已注入即返回）、防御式（任何 DOM 缺失/异常返回安全默认值、绝不抛错）。
+ */
+export const RDSH_WEBVIEW_API = `(function () {
+  if (window.__rdshWebViewApi) return;
+  function findComposer() {
+    var el = document.querySelector('[data-lexical-editor="true"]');
+    if (el) return { el: el, kind: 'lexical' };
+    el = document.querySelector('[contenteditable="true"]');
+    if (el) return { el: el, kind: 'contenteditable' };
+    el = document.querySelector('textarea');
+    if (el) return { el: el, kind: 'textarea' };
+    return null;
+  }
+  function selectAll(el) {
+    var tag = el.tagName;
+    if (tag === 'TEXTAREA' || tag === 'INPUT') { el.select(); return; }
+    var range = document.createRange();
+    range.selectNodeContents(el);
+    var sel = window.getSelection();
+    sel.removeAllRanges();
+    sel.addRange(range);
+  }
+  function insertText(el, text) {
+    el.focus();
+    try { selectAll(el); } catch (e) {}
+    // 1) execCommand 走浏览器编辑管线，让 Lexical 收到 input 事件。
+    try { if (document.execCommand('insertText', false, text)) return true; } catch (e) {}
+    // 2) 显式 beforeinput。
+    try {
+      el.dispatchEvent(new InputEvent('beforeinput', { inputType: 'insertText', data: text, bubbles: true, cancelable: true }));
+      return true;
+    } catch (e) {}
+    // 3) 兜底：直接写 DOM + 触发 input。
+    try {
+      var tag = el.tagName;
+      if (tag === 'TEXTAREA' || tag === 'INPUT') {
+        var proto = tag === 'TEXTAREA' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+        Object.getOwnPropertyDescriptor(proto, 'value').set.call(el, text);
+      } else {
+        el.textContent = text;
+      }
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+      return true;
+    } catch (e) {}
+    return false;
+  }
+  function pressEnter(el) {
+    var opts = { key: 'Enter', code: 'Enter', keyCode: 13, which: 13, bubbles: true, cancelable: true, composed: true, isComposing: false };
+    try {
+      el.dispatchEvent(new KeyboardEvent('keydown', opts));
+      el.dispatchEvent(new KeyboardEvent('keypress', opts));
+      el.dispatchEvent(new KeyboardEvent('keyup', opts));
+    } catch (e) {}
+  }
+  // 键盘守卫：语音写入后关软键盘；用户真实触摸页面即解除。
+  var keyboardGuard = false;
+  function dismissKeyboard() {
+    try {
+      var active = document.activeElement;
+      if (active && active !== document.body && typeof active.blur === 'function') active.blur();
+      var selection = window.getSelection();
+      if (selection && selection.removeAllRanges) selection.removeAllRanges();
+    } catch (e) {}
+  }
+  function onUserTouch() { if (keyboardGuard) keyboardGuard = false; }
+  document.addEventListener('focusin', function () { if (!keyboardGuard) return; dismissKeyboard(); }, true);
+  document.addEventListener('pointerdown', onUserTouch, true);
+  document.addEventListener('touchstart', onUserTouch, true);
+
+  // 单个 flow 节点的可见文本；proseOnly 额外丢弃整块代码与表格（105 只读答案正文）。
+  function answerTextOf(el, proseOnly) {
+    var clone = el.cloneNode(true);
+    var selector = '[data-variant="think"],[data-variant="others"]';
+    if (proseOnly) selector += ',pre,table';
+    var drop = clone.querySelectorAll(selector);
+    for (var i = 0; i < drop.length; i++) { if (drop[i].parentNode) drop[i].parentNode.removeChild(drop[i]); }
+    return (clone.innerText || clone.textContent || '').trim();
+  }
+  // 某个 flow kind 的最大 turn（取不到 = -1）。
+  // 111：App 用 turn / userTurn 判断"用户是否发了新消息"，从而立即停止朗读。
+  function maxTurnOf(kind) {
+    var nodes = document.querySelectorAll('[data-chat-flow-kind="' + kind + '"]');
+    var max = -1;
+    for (var i = 0; i < nodes.length; i++) {
+      var t = parseInt(nodes[i].getAttribute('data-chat-turn'), 10);
+      if (!isNaN(t) && t > max) max = t;
+    }
+    return max;
+  }
+  // 最后一轮的答案部分（排除 reasoning，取最大 turn，逐 part 拼接）。
+  // 返回 { text, turn }：turn 与该轮答案对应，供 readReply 回带给 App。
+  function latestAnswer() {
+    var steps = Array.prototype.slice.call(document.querySelectorAll('[data-chat-flow-kind="assistant-step"]'));
+    var answers = steps.filter(function (el) { return el.getAttribute('data-chat-group-part') !== 'reasoning'; });
+    var maxTurn = -1;
+    for (var i = 0; i < answers.length; i++) {
+      var turn = parseInt(answers[i].getAttribute('data-chat-turn'), 10);
+      if (!isNaN(turn) && turn > maxTurn) maxTurn = turn;
+    }
+    var parts = answers.filter(function (el) { return parseInt(el.getAttribute('data-chat-turn'), 10) === maxTurn; });
+    var texts = [];
+    for (var j = 0; j < parts.length; j++) {
+      var text = answerTextOf(parts[j], true);
+      if (text.length) texts.push(text);
+    }
+    return { text: texts.join('\\n\\n'), turn: maxTurn };
+  }
+
+  window.__rdshWebViewApi = {
+    version: 1,
+    // 104：写入 composer 并提交。返回裸状态 token。
+    fillAndSend: function (text) {
+      var found = findComposer();
+      if (!found) return 'no-composer';
+      keyboardGuard = false;
+      if (!insertText(found.el, text)) return 'fill-failed';
+      keyboardGuard = true;
+      dismissKeyboard();
+      setTimeout(function () { pressEnter(found.el); dismissKeyboard(); }, 80);
+      return 'ok';
+    },
+    // 105/111：待朗读内容 + 状态。返回 UTF-8 安全的 base64 JSON
+    // {dsh, streaming, text, turn, userTurn}（turn / userTurn 取不到时为 -1）。
+    readReply: function () {
+      var out = { dsh: false, streaming: 0, text: '', turn: -1, userTurn: -1 };
+      try {
+        out.streaming = document.querySelectorAll('[data-streaming]').length;
+        if (document.querySelectorAll('[data-chat-flow-kind]').length > 0) {
+          out.dsh = true;
+          var answer = latestAnswer();
+          out.text = answer.text;
+          out.turn = answer.turn;
+          out.userTurn = maxTurnOf('user');
+        } else {
+          out.text = document.body ? document.body.innerText : '';
+        }
+      } catch (e) {}
+      return window.btoa(unescape(encodeURIComponent(JSON.stringify(out))));
+    },
+    // 107：是否 DSH 会话页（轻量判定，可轮询）。返回裸 '1' / '0'。
+    isDshPage: function () {
+      try {
+        return document.querySelectorAll('[data-chat-flow-kind]').length > 0 ? '1' : '0';
+      } catch (e) { return '0'; }
+    }
+  };
+})();`;
+/** 把 `<script>${script}</script>` 插到 `</head>` 前（无则前置）；纯函数，可单测。 */
+export function injectHtmlScript(html, script) {
+    const tag = `<script>${script}</script>`;
+    if (html.includes("</head>"))
+        return html.replace("</head>", `${tag}</head>`);
+    return `${tag}${html}`;
+}
+//# sourceMappingURL=rdsh-webview-api.js.map

package/dist/secure-context-polyfill.d.ts

@@ -1,10 +1,14 @@
 /**
  * secure-context-polyfill.ts — 非 secure context 兼容脚本（注入 DSH 首页）。
  *
- * 背景（查档）：DSH 浏览器侧 RPC（dsh-client-connection/lib/client.js）用
- * crypto.randomUUID() 生成 MessageId/RpcId；但该 API 仅在 secure context
- * （HTTPS / localhost）可用。局域网模式为 http://<LAN-IP>（非 secure
- * context），故需 polyfill：crypto.getRandomValues 是唯一非 secure context
- * 也可用的 WebCrypto API，用它实现 UUID v4。
+ * 背景（查档）：DSH 浏览器侧 RPC 用 crypto.randomUUID()；但该 API 仅在 secure context
+ * （HTTPS / localhost）可用。局域网模式为 http://<LAN-IP>（非 secure context），故需
+ * polyfill：crypto.getRandomValues 是唯一非 secure context 也可用的 WebCrypto API。
+ *
+ * 另补 `navigator.clipboard`（同样仅 secure context 可用）：`writeText` 用
+ * `document.execCommand("copy")` + 隐藏 textarea 实现（execCommand 不受 secure context
+ * 限制，只需用户手势）。`readText` 无法安全 polyfill，保留 undefined。
  */
 export declare const SECURE_CONTEXT_POLYFILL = "(function () {\n  if (typeof crypto === \"undefined\") return;\n  if (typeof crypto.randomUUID === \"function\") return;\n  try {\n    Object.defineProperty(crypto, \"randomUUID\", {\n      value: function () {\n        var b = crypto.getRandomValues(new Uint8Array(16));\n        b[6] = (b[6] & 0x0f) | 0x40;\n        b[8] = (b[8] & 0x3f) | 0x80;\n        var h = \"\";\n        for (var i = 0; i < 16; i++) {\n          if (i === 4 || i === 6 || i === 8 || i === 10) h += \"-\";\n          h += b[i].toString(16).padStart(2, \"0\");\n        }\n        return h;\n      },\n      writable: true\n    });\n  } catch (e) { /* ignore */ }\n})();";
+/** 剪贴板 polyfill：非 secure context 下补 `navigator.clipboard.writeText`（execCommand('copy') 兜底）。 */
+export declare const CLIPBOARD_POLYFILL = "(function () {\n  if (typeof navigator === \"undefined\") return;\n  if (navigator.clipboard && typeof navigator.clipboard.writeText === \"function\") return;\n  function writeText(text) {\n    return new Promise(function (resolve, reject) {\n      var ta = document.createElement(\"textarea\");\n      ta.value = String(text);\n      ta.setAttribute(\"readonly\", \"\");\n      ta.style.position = \"fixed\";\n      ta.style.left = \"-9999px\";\n      document.body.appendChild(ta);\n      ta.select();\n      var ok = false;\n      try { ok = document.execCommand(\"copy\"); } catch (e) { /* ignore */ }\n      document.body.removeChild(ta);\n      if (ok) resolve(); else reject(new Error(\"copy failed\"));\n    });\n  }\n  try {\n    Object.defineProperty(navigator, \"clipboard\", {\n      value: { writeText: writeText },\n      writable: true,\n      configurable: true\n    });\n  } catch (e) { /* ignore */ }\n})();";

package/dist/secure-context-polyfill.js

@@ -1,11 +1,13 @@
 /**
  * secure-context-polyfill.ts — 非 secure context 兼容脚本（注入 DSH 首页）。
  *
- * 背景（查档）：DSH 浏览器侧 RPC（dsh-client-connection/lib/client.js）用
- * crypto.randomUUID() 生成 MessageId/RpcId；但该 API 仅在 secure context
- * （HTTPS / localhost）可用。局域网模式为 http://<LAN-IP>（非 secure
- * context），故需 polyfill：crypto.getRandomValues 是唯一非 secure context
- * 也可用的 WebCrypto API，用它实现 UUID v4。
+ * 背景（查档）：DSH 浏览器侧 RPC 用 crypto.randomUUID()；但该 API 仅在 secure context
+ * （HTTPS / localhost）可用。局域网模式为 http://<LAN-IP>（非 secure context），故需
+ * polyfill：crypto.getRandomValues 是唯一非 secure context 也可用的 WebCrypto API。
+ *
+ * 另补 `navigator.clipboard`（同样仅 secure context 可用）：`writeText` 用
+ * `document.execCommand("copy")` + 隐藏 textarea 实现（execCommand 不受 secure context
+ * 限制，只需用户手势）。`readText` 无法安全 polyfill，保留 undefined。
  */
 export const SECURE_CONTEXT_POLYFILL = `(function () {
   if (typeof crypto === "undefined") return;
@@ -27,4 +29,31 @@ export const SECURE_CONTEXT_POLYFILL = `(function () {
     });
   } catch (e) { /* ignore */ }
 })();`;
+/** 剪贴板 polyfill：非 secure context 下补 `navigator.clipboard.writeText`（execCommand('copy') 兜底）。 */
+export const CLIPBOARD_POLYFILL = `(function () {
+  if (typeof navigator === "undefined") return;
+  if (navigator.clipboard && typeof navigator.clipboard.writeText === "function") return;
+  function writeText(text) {
+    return new Promise(function (resolve, reject) {
+      var ta = document.createElement("textarea");
+      ta.value = String(text);
+      ta.setAttribute("readonly", "");
+      ta.style.position = "fixed";
+      ta.style.left = "-9999px";
+      document.body.appendChild(ta);
+      ta.select();
+      var ok = false;
+      try { ok = document.execCommand("copy"); } catch (e) { /* ignore */ }
+      document.body.removeChild(ta);
+      if (ok) resolve(); else reject(new Error("copy failed"));
+    });
+  }
+  try {
+    Object.defineProperty(navigator, "clipboard", {
+      value: { writeText: writeText },
+      writable: true,
+      configurable: true
+    });
+  } catch (e) { /* ignore */ }
+})();`;
 //# sourceMappingURL=secure-context-polyfill.js.map

package/dist/serve.d.ts

@@ -1,7 +1,6 @@
 export interface ServeOptions {
     host?: string;
     port?: number;
-    pairCode?: string;
     sessionTtlSeconds?: number;
     dshPath?: string;
     reset?: boolean;

package/dist/serve.js

@@ -20,7 +20,7 @@ export async function serve(opts) {
     const sessionTtlSeconds = opts.sessionTtlSeconds ?? config.sessionTtlSeconds;
     const dshPath = opts.dshPath ?? config.dshPath;
     const authMode = opts.noCode ? "none" : config.auth.mode;
-    const pairCode = opts.pairCode ?? config.auth.pairCode;
+    const accessCode = config.gateway?.accessCode ?? null;
     const foundDsh = findDsh(dshPath);
     if (foundDsh === null) {
         throw new Error("cannot find 'dsh' in PATH. Install DeepSeek Harness first, or set dshPath in config / pass --dsh <path>.");
@@ -47,22 +47,22 @@ export async function serve(opts) {
     // password + http + 非反代 → server.ts 安全约束拒绝启动（需自行提供证书）。
     const tlsMaterial = await loadTls(config.tls, config.behindProxy);
     const userManager = authMode === "password" ? new UserManager(configPath) : undefined;
-    if (opts.noCode || authMode === "none") {
-        console.warn("\n⚠  rdsh: 认证已禁用（auth.mode=none / --no-code）—— 任何能访问该端口的设备将直接操作 DSH！\n" +
-            "     仅限完全可信网络！\n");
+    if (accessCode === null && authMode !== "password") {
+        console.warn("\n⚠  rdsh: 认证已禁用（未设访问口令且 auth.mode=none）—— 任何能访问该端口的设备将直接操作 DSH！\n" +
+            "     仅限完全可信网络！用 `rdsh host gate set <口令>` 开启访问口令。\n");
     }
     let gateway;
     try {
         gateway = await startGateway({
             host,
             port,
-            pairCode,
             sessionTtlSeconds,
             dshPort: dsh.port,
             dshAuthCookieHeader,
             reset: opts.reset,
             noCode: opts.noCode,
             authMode,
+            accessCode,
             authVersion: config.auth.version,
             allowFrom: config.allowFrom,
             behindProxy: config.behindProxy,
@@ -85,7 +85,7 @@ export async function serve(opts) {
         console.log(`rdsh serve: LAN: ${lan.map((ip) => `${scheme}://${ip}:${gateway.actualPort}`).join(", ")}`);
     }
     console.log(`rdsh serve: dsh web on 127.0.0.1:${dsh.port}`);
-    console.log(`rdsh serve: auth mode: ${authMode}${authMode === "password" ? ` (config: ${configPath})` : authMode === "pair" ? ` (pair code: ${gateway.pair.codeValue()})` : ""}`);
+    console.log(`rdsh serve: auth mode: ${accessCode !== null ? "accessCode" : authMode}${authMode === "password" ? ` (config: ${configPath})` : ""}`);
     if (config.allowFrom.length > 0)
         console.log(`rdsh serve: allow_from: ${config.allowFrom.join(", ")}`);
     if (tlsMaterial !== null)
@@ -94,8 +94,8 @@ export async function serve(opts) {
         console.log("rdsh serve: behind_proxy: true (TLS terminated by reverse proxy)");
     if (authMode === "password")
         console.log("rdsh serve: sign in with `rdsh user` credentials in the browser login page.");
-    else if (authMode === "pair")
-        console.log("rdsh serve: enter the pair code in the browser on your other device.");
+    else if (accessCode !== null)
+        console.log("rdsh serve: 访问口令已启用（经隧道或直连访问都需先输入口令）。");
     let shuttingDown = false;
     const shutdown = async (signal) => {
         if (shuttingDown)