@cowwo/dsh-lookout 0.5.2 → 0.5.3

package/client/client.js

@@ -7293,6 +7293,11 @@ window.__ModuleLoader__.load({
   const ROW_MENU_BODY_SELECTOR = "[data-files-body]";
   const ROW_MENU_ROWS_SELECTOR = 'li[data-files-entry="file"],li[data-files-entry="directory"]';
   const ROW_MENU_PATH_ATTR = "data-files-path";
+  /** Same-origin download route: HEAD is our pre-flight, the browser streams the GET. */
+  const ROW_MENU_DOWNLOAD_ROUTE = "/api/lookout.download";
+  /** Where the current session id is read from, sidebar marker first, storage second. */
+  const ROW_MENU_SESSION_ATTR = "data-sidebar-right-session";
+  const ROW_MENU_SESSION_KEY = "dsh.sessions.current";
   /** A run that places nothing at all, this many times in a row, gives up. */
   const ROW_MENU_MAX_FAILURES = 3;
   const ROW_MENU_SCAN_DEBOUNCE = 200;
@@ -7322,12 +7327,13 @@ window.__ModuleLoader__.load({
     download: "下载",
     folderUnsupported: "文件夹暂不支持",
     copyFailed: "复制失败，请手动选择路径",
+    err400: "下载参数不完整：缺少会话或文件路径",
     err401: "登录已过期，请刷新页面重新登录",
-    err413: "文件太大，超出服务器允许的下载上限",
     err404: "文件不存在或已被删除",
-    err403: "没有权限读取这个文件",
+    err403: "只能下载当前会话工作区内的文件",
     errOther: "下载失败（HTTP {status}）",
     errNetwork: "下载失败，请检查连接",
+    errSession: "无法确定当前会话，已取消下载",
     givingUp: "文件行「⋯」菜单连续注入失败，已自动停止；文件树本身不受影响。",
     dismiss: "不再提示"
   };
@@ -7340,12 +7346,13 @@ window.__ModuleLoader__.load({
     download: "Download",
     folderUnsupported: "Folders not supported",
     copyFailed: "Copy failed — select the path and copy it manually",
+    err400: "The download request is incomplete: missing session or file path.",
     err401: "Your session has expired. Refresh the page and sign in again.",
-    err413: "This file is larger than the server's download limit.",
     err404: "The file no longer exists or was deleted.",
-    err403: "You do not have permission to read this file.",
+    err403: "You can only download files inside the current session's workspace.",
     errOther: "Download failed (HTTP {status}).",
     errNetwork: "Download failed — check your connection.",
+    errSession: "Cannot determine the current session — download cancelled.",
     givingUp: "The file-row ⋯ menu could not be injected repeatedly and stopped; the file tree itself is unaffected.",
     dismiss: "Do not show again"
   };
@@ -8133,18 +8140,49 @@ window.__ModuleLoader__.load({
 
     function downloadErrorText(status) {
       switch (status) {
+        case 400: return translate("err400");
         case 401: return translate("err401");
-        case 413: return translate("err413");
-        case 404: return translate("err404");
         case 403: return translate("err403");
+        case 404: return translate("err404");
         default: return translate("errOther", { status: status > 0 ? status : "?" });
       }
     }
 
+    /** The current session id: sidebar marker first, persisted pointer second, "" if neither. */
+    function currentSessionId() {
+      try {
+        const marker = document.querySelector("[" + ROW_MENU_SESSION_ATTR + "]");
+        const attr = marker !== null && marker !== undefined ? marker.getAttribute(ROW_MENU_SESSION_ATTR) : null;
+        if (typeof attr === "string" && attr !== "") return attr;
+      } catch (error) { /* fall through to storage */ }
+      try {
+        const stored = window.localStorage.getItem(ROW_MENU_SESSION_KEY);
+        if (typeof stored === "string" && stored !== "") return stored;
+      } catch (error) { /* no storage: no session */ }
+      return "";
+    }
+
+    function downloadUrl(sessionId, path) {
+      return ROW_MENU_DOWNLOAD_ROUTE
+        + "?sessionId=" + encodeURIComponent(sessionId)
+        + "&path=" + encodeURIComponent(path);
+    }
+
+    /**
+     * Download without ever holding the file: HEAD pre-flights the route, then a
+     * plain <a download> lets the browser stream its own GET to disk. A failed
+     * pre-flight never starts a download, it only explains why.
+     */
     async function downloadRowFile(path) {
+      const sessionId = currentSessionId();
+      if (sessionId === "") {
+        if (!disposed) showToast(translate("errSession"), false);
+        return;
+      }
+      const url = downloadUrl(sessionId, path);
       let response = null;
       try {
-        response = await window.fetch("api/file?path=" + encodeURIComponent(path), { credentials: "same-origin" });
+        response = await window.fetch(url, { method: "HEAD", credentials: "same-origin" });
       } catch (error) {
         if (!disposed) showToast(translate("errNetwork"), false);
         return;
@@ -8154,19 +8192,16 @@ window.__ModuleLoader__.load({
         if (!disposed) showToast(downloadErrorText(status), false);
         return;
       }
+      if (disposed) return;
       try {
-        const blob = await response.blob();
-        if (disposed) return;
-        const objectUrl = window.URL.createObjectURL(blob);
         const link = document.createElement("a");
-        link.href = objectUrl;
+        link.href = url;
         link.download = fileNameFor(path);
         link.rel = "noopener";
         link.style.display = "none";
         document.body.appendChild(link);
         link.click();
         link.remove();
-        window.setTimeout(() => { try { window.URL.revokeObjectURL(objectUrl); } catch { /* gone */ } }, 1000);
       } catch (error) {
         if (!disposed) showToast(translate("errNetwork"), false);
       }

package/lib/download.js

@@ -0,0 +1,344 @@
+/**
+ * dsh-lookout · 宿主侧流式下载路由
+ *
+ * 一条精确的 Fetch 路由 `GET|HEAD /api/lookout.download`，把**某个会话 cwd 之内**的
+ * 一个普通文件流式发给浏览器（内存恒定：createReadStream → Readable.toWeb → Response）。
+ *
+ * 三条硬约束（改代码时别动）：
+ *   1. 路径逐段必须匹配 [A-Za-z0-9_$.-]+，且宿主强制 `/api/` 前缀——所以是
+ *      `/api/lookout.download` 这个字面量，不能把参数拼进路径。
+ *   2. **不要把 connection/fs 塞进 lib/index.js 顶层的 inject 数组**：那会让没有 web 载体的
+ *      组合（CLI）一直等不到服务、卡死插件加载。这里用 ctx.inject 局部等待。
+ *   3. 放行判定是"词法归一化 + realpath"两道：只有词法那道挡不住符号链接逃逸。
+ *
+ * 错误码：缺参/非绝对路径 400；越界或非普通文件 403；不存在 404；其它 500（只 warn 一次，不吐堆栈）。
+ */
+import { createReadStream, fstat } from 'node:fs'
+import { realpath } from 'node:fs/promises'
+import { Readable } from 'node:stream'
+import { basename, isAbsolute, normalize, sep } from 'node:path'
+
+/** 路由路径：宿主强制 /api/ 前缀，且每段要过 [A-Za-z0-9_$.-]+ 校验。 */
+export const DOWNLOAD_ROUTE_PATH = '/api/lookout.download'
+
+/** 同一路由路径的短名（老调用方只认这个名字）。 */
+export const DOWNLOAD_ROUTE = DOWNLOAD_ROUTE_PATH
+
+/** 认不出扩展名时一律给这个，避免浏览器瞎猜。 */
+const DEFAULT_CONTENT_TYPE = 'application/octet-stream'
+
+/**
+ * 最小扩展名映射。只有一张表，不做内容嗅探：下载场景里"猜错"比"给 stream"更糟。
+ * @type {Record<string, string>}
+ */
+const CONTENT_TYPES = {
+	'.txt': 'text/plain',
+	'.md': 'text/markdown',
+	'.json': 'application/json',
+	'.csv': 'text/csv',
+	'.html': 'text/html',
+	'.css': 'text/css',
+	'.js': 'text/javascript',
+	'.mjs': 'text/javascript',
+	'.xml': 'application/xml',
+	'.yaml': 'text/yaml',
+	'.yml': 'text/yaml',
+	'.png': 'image/png',
+	'.jpg': 'image/jpeg',
+	'.jpeg': 'image/jpeg',
+	'.gif': 'image/gif',
+	'.webp': 'image/webp',
+	'.svg': 'image/svg+xml',
+	'.pdf': 'application/pdf',
+	'.zip': 'application/zip',
+	'.gz': 'application/gzip',
+	'.mp3': 'audio/mpeg',
+	'.wav': 'audio/wav',
+	'.mp4': 'video/mp4',
+}
+
+/**
+ * 按扩展名给出 content-type。
+ * @param {string} fileName 文件名（大小写不敏感）
+ * @returns {string} MIME 类型；认不出给 application/octet-stream
+ */
+export function contentTypeOf(fileName) {
+	const dot = fileName.lastIndexOf('.')
+	if (dot <= 0) return DEFAULT_CONTENT_TYPE
+	return CONTENT_TYPES[fileName.slice(dot).toLowerCase()] ?? DEFAULT_CONTENT_TYPE
+}
+
+/**
+ * content-disposition 里 filename="..." 那份的 ASCII 兜底：
+ * 非可见 ASCII 与引号/反斜杠一律换成下划线，空名字退回 download。
+ * @param {string} fileName 原始文件名
+ * @returns {string} 纯 ASCII 文件名
+ */
+export function asciiFileName(fileName) {
+	const cleaned = String(fileName).replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_').trim()
+	return cleaned.length === 0 ? 'download' : cleaned
+}
+
+/**
+ * 拼完整的 content-disposition：ASCII 兜底 + RFC 5987 的 filename*（真名，中文不丢）。
+ * @param {string} fileName 原始文件名
+ * @returns {string} 头值
+ */
+export function contentDisposition(fileName) {
+	const name = String(fileName ?? '')
+	return `attachment; filename="${asciiFileName(name)}"; filename*=UTF-8''${encodeURIComponent(name || 'download')}`
+}
+
+/**
+ * 判定 candidate 是否落在 root 之内（root 自身算在内）。两边都应是已归一化的绝对路径。
+ * @param {string} root 边界目录
+ * @param {string} candidate 待判定路径
+ * @returns {boolean} 是否在范围内
+ */
+export function withinRoot(root, candidate) {
+	if (candidate === root) return true
+	const base = root.endsWith(sep) ? root : root + sep
+	return candidate.startsWith(base)
+}
+
+/**
+ * 读一个宿主服务：先用 Reflect.get（普通对象与 ctx 都吃），再退回 ctx.get。
+ * @param {object} ctx 上下文（真实 ctx、inject 回调里的 scoped，或 {fs, sessions} 这类直给对象）
+ * @param {string} name 服务名
+ * @returns {any} 服务实例或 undefined
+ */
+function serviceOf(ctx, name) {
+	const direct = Reflect.get(ctx, name)
+	if (direct !== undefined && direct !== null) return direct
+	return typeof ctx?.get === 'function' ? ctx.get(name) : undefined
+}
+
+/**
+ * 取会话 cwd。字段名现场确认过：dsh-session 的 Session 上是 `session.header.cwd`
+ * （SessionHeader.cwd，创建时校验必须是绝对路径字符串）；`meta.cwd` / `cwd` 只作兜底。
+ * @param {object|undefined} session ctx.sessions.get() 的返回值
+ * @returns {string|undefined} 绝对路径 cwd
+ */
+export function sessionCwd(session) {
+	if (session === null || typeof session !== 'object') return undefined
+	const candidates = [session.header?.cwd, session.meta?.cwd, session.cwd]
+	for (const value of candidates) if (typeof value === 'string' && value.length > 0) return value
+	return undefined
+}
+
+/**
+ * 取某个会话的工作区目录（下载的边界）。先 get，拿不到再在 list 里按 id 匹配一次。
+ * @param {object|undefined} sessions ctx.sessions
+ * @param {string} sessionId 会话 id
+ * @returns {string|null} 绝对路径，取不到给 null
+ */
+export function sessionWorkspace(sessions, sessionId) {
+	if (sessions === null || typeof sessions !== 'object') return null
+	if (typeof sessions.get === 'function') {
+		const cwd = sessionCwd(sessions.get(sessionId))
+		if (cwd !== undefined) return cwd
+	}
+	if (typeof sessions.list === 'function') {
+		for (const session of sessions.list() ?? []) {
+			if (session?.header?.id === sessionId || session?.id === sessionId) {
+				const cwd = sessionCwd(session)
+				if (cwd !== undefined) return cwd
+			}
+		}
+	}
+	return null
+}
+
+/**
+ * realpath 的"宽容版"：路径不存在/无权限时原样返回，让后面的 stat 去定 404。
+ * @param {string} path 绝对路径
+ * @returns {Promise<string>} realpath，或原路径
+ */
+async function realPathOrSelf(path) {
+	try {
+		return await realpath(path)
+	} catch {
+		return path
+	}
+}
+
+/**
+ * 统一的错误响应：纯文本 + 禁缓存。
+ * @param {number} status HTTP 状态码
+ * @param {string} message 一行说明（不吐内部细节）
+ * @returns {Response} 响应
+ */
+function errorResponse(status, message) {
+	return new Response(message, {
+		status,
+		headers: {
+			'content-type': 'text/plain; charset=utf-8',
+			'cache-control': 'private, no-store',
+		},
+	})
+}
+
+/**
+ * 把 fs 层的失败翻译成状态码：FS_NOT_FOUND / ENOENT 当"不存在"，其它交给外层 500。
+ * @param {unknown} error 抛出的错误
+ * @returns {boolean} 是否属于"不存在"
+ */
+function isNotFound(error) {
+	const code = error !== null && typeof error === 'object' ? error.code : undefined
+	return code === 'FS_NOT_FOUND' || code === 'ENOENT'
+}
+
+/**
+ * 造一个下载 handler。
+ *
+ * deps 只为一件事存在：单测要数"到底有没有真去读文件"。生产路径不传，用 node:fs 的真身。
+ * @param {object} ctx 上下文（真实 ctx / inject 回调里的 scoped / {fs, sessions} 直给对象）
+ * @param {{createReadStream?: typeof createReadStream}} [deps] 可替换的底层流工厂
+ * @returns {(request: Request) => Promise<Response>} Fetch handler
+ */
+export function createDownloadHandler(ctx, deps = {}) {
+	const openStream = typeof deps.createReadStream === 'function' ? deps.createReadStream : createReadStream
+
+	return async function handleDownload(request) {
+		try {
+			const signal = request.signal
+			const params = new URL(request.url).searchParams
+			const sessionId = params.get('sessionId')
+			const requestedPath = params.get('path')
+
+			// —— 400：参数这一关先过，不合法就不碰文件系统 ——
+			if (sessionId === null || sessionId.length === 0) return errorResponse(400, 'missing sessionId')
+			if (requestedPath === null || requestedPath.length === 0) return errorResponse(400, 'missing path')
+			if (!isAbsolute(requestedPath)) return errorResponse(400, 'path must be absolute')
+			// 尾随分隔符是"目录写法"：按"没有这个文件"处理，别让它走到 stat 再变成 500。
+			if (/[\\/]$/.test(requestedPath)) return errorResponse(404, 'file not found')
+
+			const sessions = serviceOf(ctx, 'sessions')
+			if (sessions === undefined) return errorResponse(500, 'download unavailable: missing sessions service')
+
+			// —— 403：会话或它的 cwd 拿不到，就没有边界可谈 ——
+			const cwd = sessionWorkspace(sessions, sessionId)
+			if (cwd === null) return errorResponse(403, 'session cwd unavailable')
+
+			// —— 第一道：词法归一化（挡 .. 这类纯文本穿越） ——
+			const root = normalize(cwd)
+			const candidate = normalize(requestedPath)
+			if (!withinRoot(root, candidate)) return errorResponse(403, 'path outside session cwd')
+
+			const fs = serviceOf(ctx, 'fs')
+			if (typeof fs?.resolve !== 'function' || typeof fs?.stat !== 'function' || typeof fs?.processPath !== 'function') {
+				return errorResponse(500, 'download unavailable: missing fs service')
+			}
+
+			let target
+			let rootTarget
+			try {
+				target = await fs.resolve(candidate, { signal })
+				rootTarget = await fs.resolve(root, { signal })
+			} catch (error) {
+				if (isNotFound(error)) return errorResponse(404, 'file not found')
+				throw error
+			}
+
+			// —— 第二道：realpath 之后仍在范围内（挡符号链接逃逸） ——
+			// 双保险：既信后端的 processPath（本地后端本身就是 realpath 结果），
+			// 也自己 realpath 一次，后端换成非 realpath 的实现时这道闸照样有效。
+			const realRoot = String(fs.processPath(rootTarget))
+			const hostPath = String(fs.processPath(target))
+			const [realRootPath, realTargetPath] = await Promise.all([realPathOrSelf(realRoot), realPathOrSelf(hostPath)])
+			if (!withinRoot(realRootPath, realTargetPath)) return errorResponse(403, 'path outside session cwd after realpath')
+
+			let info
+			try {
+				info = await fs.stat(target, signal)
+			} catch (error) {
+				if (isNotFound(error) || error?.code === 'ENOTDIR' || error?.code === 'EISDIR') return errorResponse(404, 'file not found')
+				throw error
+			}
+			if (info === undefined) return errorResponse(404, 'file not found')
+			if (info.type !== 'file') return errorResponse(403, 'not a regular file')
+
+			const fileName = basename(candidate)
+			const headers = {
+				'content-type': contentTypeOf(fileName),
+				'content-disposition': contentDisposition(fileName),
+				'cache-control': 'private, no-store',
+			}
+			// 后端不保证给 size；缺了就不写 content-length（宁可不写，也不写一个假的 0）。
+			let declaredSize = 0
+			if (typeof info.size === 'number' && Number.isFinite(info.size) && info.size >= 0) {
+				declaredSize = info.size
+				headers['content-length'] = String(info.size)
+			}
+
+			// HEAD 只要头：同样的 status + headers，body 必须为空，且**不打开文件**。
+			if (request.method === 'HEAD') return new Response(null, { status: 200, headers })
+
+			const stream = openStream(realTargetPath)
+			// 打开后用同一个 fd 复核一次大小：stat 与 open 之间被换掉的极端情况，
+			// 宁可断流也不要发出一份长度对不上的响应。
+			stream.once('open', (fd) => {
+				if (declaredSize === 0) return
+				try {
+					fstat(fd, (error, stats) => {
+						if (error === null && stats !== undefined && stats.size !== declaredSize) stream.destroy(new Error('size changed while downloading'))
+					})
+				} catch { /* best effort */ }
+			})
+			stream.on('error', (error) => {
+				const code = error?.code ?? ''
+				// 客户端主动取消/连接被掐断是常态，不该刷日志。
+				if (code === 'ERR_STREAM_PREMATURE_CLOSE' || code === 'ECONNRESET' || code === 'EPIPE' || error?.name === 'AbortError') return
+				console.warn('[dsh-lookout] download stream failed:', code !== '' ? code : (error?.message ?? error))
+			})
+			return new Response(Readable.toWeb(stream), { status: 200, headers })
+		} catch (error) {
+			// 500 只说一句，不带堆栈：日志里也不要整段内部路径。
+			console.warn('[dsh-lookout] download route failed:', error?.message ?? error)
+			return errorResponse(500, 'download failed')
+		}
+	}
+}
+
+/**
+ * 把下载路由挂到 connection 上。
+ *
+ * 用 ctx.inject 局部等 connection/fs/sessions：缺任何一个就不注册，而不是让整个插件
+ * 卡在加载阶段（那正是不能把它们塞进顶层 inject 的原因）。
+ * @param {object} ctx 插件上下文
+ * @param {{createReadStream?: typeof createReadStream}} [deps] 仅单测使用
+ * @returns {void}
+ */
+const REGISTERED_CONNECTIONS = new WeakSet()
+
+export function registerDownloadRoute(ctx, deps = {}) {
+	const attach = (scoped) => {
+		const connection = serviceOf(scoped, 'connection')
+		if (typeof connection?.fetch?.register !== 'function') return
+		// 同一个 connection 只挂一次：宿主对重复路径会直接抛错，抛在 apply 里会带崩整个插件。
+		if (REGISTERED_CONNECTIONS.has(connection)) return
+		const route = {
+			path: DOWNLOAD_ROUTE_PATH,
+			methods: ['GET', 'HEAD'],
+			requestBody: 'buffered',
+			fetch: createDownloadHandler(scoped, deps),
+		}
+		const register = () => {
+			if (REGISTERED_CONNECTIONS.has(connection)) return
+			try {
+				const dispose = connection.fetch.register(route)
+				REGISTERED_CONNECTIONS.add(connection)
+				return dispose
+			} catch (error) {
+				// 已经被别人占了同名路径（或宿主换了校验）：记一条，不拖累插件加载。
+				console.warn('[dsh-lookout] download route not registered:', error?.code ?? error?.message ?? error)
+				return undefined
+			}
+		}
+		// 包一层 effect：插件卸载时路由跟着撤掉。
+		if (typeof scoped?.effect === 'function') scoped.effect(register, `dsh-lookout: ${DOWNLOAD_ROUTE_PATH}`)
+		else register()
+	}
+	if (typeof ctx?.inject === 'function') ctx.inject(['connection', 'fs', 'sessions'], attach)
+	else attach(ctx)
+}

package/lib/index.js

@@ -22,6 +22,7 @@ import { FaviconCustomService } from './icon/index.js'
 import { apply as applyNotify } from './notify/index.js'
 import { apply as applySessionInfo } from './session/index.js'
 import { MailSchema } from './notify/config.js'
+import { registerDownloadRoute } from './download.js'
 
 export const name = 'dsh-lookout'
 
@@ -68,4 +69,6 @@ export function apply(ctx, config) {
 	applyNotify(ctx, config)
 	// ③ C:宿主侧本来就是空实现。
 	applySessionInfo(ctx)
+	// ④ 宿主流式下载路由:自己 inject(connection/fs/sessions),缺服务就不挂,不动顶层 inject。
+	registerDownloadRoute(ctx)
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cowwo/dsh-lookout",
   "description": "瞭望哨：盯着你的每个会话——谁跑完了、谁出错了、谁卡住了、谁在等你审批，用浏览器图标角标、红点/黄点和邮件通知你；顺带显示当前会话 ID。· Lookout: watches every session — who finished, who errored, who is stuck, and who is waiting for your approval — and notifies you through the browser favicon badge, red/yellow dots, and email, while also showing the current session ID.",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",