dsh-plan-completion 0.1.0 → 0.1.2

package/docs/security.md

@@ -0,0 +1,64 @@
+# 安全与隐私边界
+
+本页描述 **v0.1.2** 的安全与隐私边界。历史版本（npm `0.1.0`/`0.1.1`）不包含本页描述的全部加固，请以 registry 最新版为准。
+
+## 本地计划存储（v0.1.2）
+
+- 计划与最近一条建议按会话写入 `storageDir`（默认 `~/.dsh/plan-completion-data`）下的明文 JSON 文件，用于 DSH 重启恢复；
+- 文件包含计划步骤、更新原因、建议文本等**由会话内容派生的数据**；不加密、不自动过期/清理，无文件锁（单进程假设）；
+- 同一机器多 profile 共用默认目录时可能互相看到计划；多用户共享机器不应使用默认目录；
+- `persistPlans: false` 完全关闭磁盘持久化；`storageDir` 可指向受控目录。
+
+## 请求访问
+
+所有 `/plan-completion/*` 路由在读取请求体或执行操作前调用 DSH 的
+`connection.requestRejection(req)`。宿主负责 Host/Origin 检查及 cookie/API peer 鉴权；
+无凭据、来源不受信任时返回 401/403，服务不可用或契约异常时返回 503，不退回“仅检查 loopback”。
+插件不反射任意 Origin、不开放跨来源凭据 CORS。
+
+默认只有 `state`、`replan`、`warm`。只有显式开启 `enableDebugRoutes: true` 才注册
+`debug`、`diag`、`theme`、`experiment`、`autojob`、`steps`、`reset`，这些端点仍须鉴权。
+DSH 是当前用户的可信宿主；本插件没有额外的多租户/逐会话 ACL。获得合法 DSH peer
+权限的客户端仍能访问该宿主内的计划，不应把这一机制当作多人共享服务的隔离边界。
+
+已核对本机安装版宿主源码：WebServer 不替插件鉴权；Electron 的 dsh-app HTTP 代理会
+去掉 renderer 的 Origin 并注入宿主 cookie，因此客户端继续使用 same-origin fetch。
+回归测试使用真实插件入口和模拟宿主服务；没有替换运行中的 DSH 或开展真实浏览器攻击测试。
+
+## 哪些内容会发送给模型
+
+默认 `modelCalls: true`。计划生成会把目标、近期用户/助手消息、工具错误及已有步骤证据
+组成提示词，经 DSH llm 服务发送到**宿主当前默认 provider/model**。它不一定是历史会话
+原先使用的模型，也不保证是本地模型。长度裁剪不是敏感信息脱敏；不要假定正文里的密码、
+个人信息或业务数据会被自动识别和移除。
+
+修复后不再遍历其他供应商挑选更快模型，也不缓存已过时的默认选择；无可用默认路由时使用启发式。
+调试实验的评审也使用同一已选路线，结果不再声称来自独立跨模型评审。
+`modelCalls: false` 可关闭**本插件**的全部模型调用并使用启发式，不会关闭 DSH 主 agent 的模型调用。
+
+`warmBackfill: true` 会在打开旧会话时读取持久化历史以生成计划，可能触发模型请求。
+设为 false 可关闭历史回填；若希望插件不向模型传输任何会话内容，同时设置 modelCalls: false。
+
+## 本地日志、诊断及截图
+
+- debugDir 默认为空，不写运行日志；设置目录或 DSH_PLAN_COMPLETION_DEBUG_DIR 后才启用。
+- 运行日志仅保留允许列表中的操作元数据；会话标识使用截短 SHA-256。
+  不保留模型正文、原始错误、配置内容、请求 URL/查询串、UA 或客户端请求体。
+  会话哈希仍是可关联的假名标识，日志不是匿名统计。
+- 客户端不再发送 DOM 正文、补全建议文本或完整页面 URL。
+  诊断端点再次按白名单保留布局尺寸和布尔值，忽略额外正文。
+- 显式运行调试实验时，内存结果和 debugDir 下的实验 JSON 仍可能含计划、建议、
+  模型评审原文等内容。应按会话内容保护，不要把 research/debug 文件提交或公开。
+  这些文件不加密，也没有自动保留期限。
+- 仓库现有四张截图未见密钥/cookie 等凭据，但包含昵称头像、费用用量、模型与开发任务内容。
+  这类演示信息已经公开；后续公开演示宜换为虚构样本或仅截取插件区域。
+
+## 本次验证范围
+
+原代码的未鉴权访问和隐式跨 provider 发送，均用合成数据、离线 mock 复现。
+修复后的测试覆盖未授权/错误来源/鉴权服务缺失、诊断默认关闭、日志内容排除、
+默认模型切换、关闭模型调用，以及计划状态和前端生命周期。
+
+当前文本文件扫描未匹配常见私钥、GitHub/API/AWS 密钥模式；这不是完整 Git 历史扫描，
+也不能证明不存在所有形式的秘密。没有在真实模型端点、生产 DSH/Electron 或 npm 发布环境
+上执行端到端验收；本次运行结果不可替代部署后的兼容性验证。

package/host/security.js

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto';
+
+// DSH owns Host/Origin checking and cookie/API-peer authentication.
+// Fail closed during service startup/shutdown and with incompatible hosts.
+export function requestRejection(connection, req) {
+  try {
+    if (typeof connection?.requestRejection !== 'function') return 503;
+    const rejection = connection.requestRejection(req);
+    if (rejection === undefined) return undefined;
+    return rejection === 401 || rejection === 403 ? rejection : 503;
+  } catch {
+    return 503;
+  }
+}
+
+const numberKeys = new Set(['turn', 'seq', 'elapsed', 'elapsedMs', 'events', 'maxTokens',
+  'textChars', 'total', 'index', 'stepCount', 'at', 'fullEvidenceChars']);
+const booleanKeys = new Set(['force', 'ok', 'hasSuggestion', 'suggestion',
+  'withinSuggestionDeadline', 'existed', 'cookie']);
+const labelKeys = new Set(['phase', 'outcome', 'step', 'source', 'method', 'mode', 'type', 'code']);
+
+// Keep operational metadata only. Raw errors, model text, config, URLs, user agent,
+// request bodies and model/provider details may contain conversation data or credentials.
+export function safeDebugRecord(record = {}) {
+  const safe = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (numberKeys.has(key) && Number.isFinite(value)) safe[key] = value;
+    else if (booleanKeys.has(key) && typeof value === 'boolean') safe[key] = value;
+    else if (labelKeys.has(key) && typeof value === 'string' && /^[a-zA-Z0-9_./:-]{1,80}$/.test(value)) safe[key] = value;
+  }
+  if (typeof record.sessionId === 'string' && record.sessionId) {
+    safe.sessionHash = createHash('sha256').update(record.sessionId).digest('hex').slice(0, 16);
+  }
+  if (record.error !== undefined) safe.error = true;
+  if (record.usage && typeof record.usage === 'object') {
+    safe.usage = Object.fromEntries(Object.entries(record.usage)
+      .filter(([key, value]) => /^(input|output|total|prompt|completion|cached|reasoning)(Tokens|_tokens)$/.test(key)
+        && Number.isFinite(value) && value >= 0));
+  }
+  return safe;
+}
+
+// Browser diagnostics are untrusted input, including with a valid DSH cookie.
+// Retain only layout dimensions/booleans, never arbitrary DOM text or URLs.
+export function safeDiagnostics(input) {
+  const source = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+  const result = {};
+  for (const key of ['hasPill', 'hasEntry', 'suggestVisible', 'dockPresent', 'heroVisible']) {
+    if (typeof source[key] === 'boolean') result[key] = source[key];
+  }
+  if (['module-load', 'dom-check'].includes(source.phase)) result.phase = source.phase;
+  if (typeof source.build === 'string' && /^[a-zA-Z0-9._:-]{1,80}$/.test(source.build)) result.build = source.build;
+  if (Number.isFinite(source.rowHeight)) result.rowHeight = source.rowHeight;
+  for (const key of ['heroStyle', 'rowStyle', 'suggestStyle', 'entryStyle', 'composerStyle']) {
+    const style = source[key];
+    if (!style || typeof style !== 'object') continue;
+    result[key] = {};
+    for (const dimension of ['left', 'top', 'w', 'h']) {
+      if (Number.isFinite(style[dimension])) result[key][dimension] = style[dimension];
+    }
+    if (['none', 'block', 'inline', 'inline-block', 'flex', 'inline-flex', 'grid', 'contents'].includes(style.display)) {
+      result[key].display = style.display;
+    }
+  }
+  return result;
+}

package/host/store.js

@@ -5,7 +5,9 @@
  *
  * 语义（两个 store 一致）：
  *   get(sessionId)              → plan | null（返回副本，改它不影响存储）
- *   put(plan, {cas})            → boolean；cas 省略=无条件写，null=仅新建，{gen,rev}=期望当前版本
+ *   getState(sessionId)         → { plan, suggestion } | null（持久化恢复用）
+ *   put(plan, {cas,suggestion}) → boolean；cas 省略=无条件写，null=仅新建，{gen,rev}=期望当前版本；
+ *                                 suggestion 存在时一并保存最近一次建议（undefined=保持不变）
  *   history(sessionId)          → plan[]（旧 → 新，含当前版本）
  *   prune(n = 5)                → 每会话只保留最近 n 版
  *   clear(sessionId?)           → boolean | number
@@ -25,6 +27,10 @@ import { validVersion, versionEquals } from './plan.js';
 const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 const isNonEmptyStr = (v) => typeof v === 'string' && v.trim().length > 0;
 
+function hasOwn(obj, key) {
+  return isObj(obj) && Object.prototype.hasOwnProperty.call(obj, key);
+}
+
 function clone(value) {
   if (value == null) return value;
   try {
@@ -69,7 +75,7 @@ function pushHistory(state, plan) {
  * @returns {object}
  */
 export function createMemoryStore() {
-  /** @type {Map<string, {plan: object, history: object[]}>} */
+  /** @type {Map<string, {plan: object, suggestion: object|null, history: object[]}>} */
   const states = new Map();
 
   function get(sessionId) {
@@ -78,13 +84,21 @@ export function createMemoryStore() {
     return state && state.plan ? clone(state.plan) : null;
   }
 
+  function getState(sessionId) {
+    if (!isNonEmptyStr(sessionId)) return null;
+    const state = states.get(sessionId);
+    if (!state || !state.plan) return null;
+    return { plan: clone(state.plan), suggestion: state.suggestion ?? null };
+  }
+
   function put(plan, options = {}) {
     if (!lightValidate(plan)) return false;
-    const cas = isObj(options) && Object.prototype.hasOwnProperty.call(options, 'cas') ? options.cas : undefined;
+    const cas = hasOwn(options, 'cas') ? options.cas : undefined;
     const sessionId = plan.sessionId;
-    const state = states.get(sessionId) ?? { plan: null, history: [] };
+    const state = states.get(sessionId) ?? { plan: null, suggestion: null, history: [] };
     if (!casMatches(cas, state)) return false;
     state.plan = clone(plan);
+    if (hasOwn(options, 'suggestion')) state.suggestion = clone(options.suggestion) ?? null;
     pushHistory(state, plan);
     states.set(sessionId, state);
     return true;
@@ -124,7 +138,7 @@ export function createMemoryStore() {
     return [...states.keys()];
   }
 
-  return { get, put, history, prune, clear, listSessions, size: () => states.size };
+  return { get, getState, put, history, prune, clear, listSessions, size: () => states.size };
 }
 
 /* ──────────────────────────────────────────────────────────────
@@ -171,15 +185,22 @@ export function createFileStore(dir) {
       const data = await readState(sessionId);
       return data && isObj(data.plan) ? clone(data.plan) : null;
     },
+    async getState(sessionId) {
+      if (!enabled || !isNonEmptyStr(sessionId)) return null;
+      const data = await readState(sessionId);
+      if (!data || !isObj(data.plan)) return null;
+      return { plan: clone(data.plan), suggestion: isObj(data.suggestion) ? clone(data.suggestion) : null };
+    },
     async put(plan, options = {}) {
       if (!enabled || !lightValidate(plan)) return false;
       try {
-        const cas = isObj(options) && Object.prototype.hasOwnProperty.call(options, 'cas') ? options.cas : undefined;
+        const cas = hasOwn(options, 'cas') ? options.cas : undefined;
         const sessionId = plan.sessionId;
-        const data = (await readState(sessionId)) ?? { sessionId, plan: null, history: [] };
+        const data = (await readState(sessionId)) ?? { sessionId, plan: null, suggestion: null, history: [] };
         if (!casMatches(cas, data)) return false;
         data.plan = clone(plan);
         data.sessionId = sessionId;
+        if (hasOwn(options, 'suggestion')) data.suggestion = clone(options.suggestion) ?? null;
         if (!Array.isArray(data.history)) data.history = [];
         const last = data.history[data.history.length - 1];
         if (last && versionEquals(last.version, plan.version)) data.history[data.history.length - 1] = clone(plan);