fix: preview explicit files outside workspace

Author: laoyh

README.md

@@ -277,7 +277,7 @@ GitHub topic [`dsh-better-sidebar`](https://github.com/topics/dsh-better-sidebar
 
 - 🌿 **「文件变动」统一 tab**（#475）：Git 视角（真 diff / 历史 / 暂存·提交·还原 / worktree·子仓库选择）与本轮文件视角（模型读/写/编辑实时追踪）双视角合一；统一 diff 渲染（改蓝配对 + 行内字符级高亮 + 语法着色 + 上下文折叠）、底部可拖拽预览面板、一键展开独立 diff tab
 - 💬 **侧边对话渲染升级**（#486）：主对话级 Blocks 结构、turn 用量尾标、断线重连横幅
-- ⚙️ **工作区路径围栏开关**（#458）：新增 `workspaceFence` 声明式设置键，工作区外路径 403 时错误面一键关闭并指引
+- ⚙️ **工作区路径围栏与外部预览**：`workspaceFence` 继续约束文件树、保存、重命名、删除和上传；明确打开的绝对文件允许在工作区外只读预览（文本、媒体和HTML），不存在或不可读时返回明确的文件系统错误
 
 **⚡ 性能**
 

README_EN.md

@@ -281,7 +281,7 @@ All changes since v0.17.1 (the two intermediate version numbers v0.18.1-alpha.0
 
 - 🌿 **Unified "Changes" tab** (#475): one tab, two lenses — Git (real diff / history / stage·commit·revert / worktree & child-repo selection) and This Session (live tracking of every file the model reads / writes / edits); a unified diff renderer (mod pairing + intra-line character highlights + syntax coloring + context folding), a draggable bottom preview pane, and one-click expansion into a dedicated diff tab
 - 💬 **Side Chat rendering upgrade** (#486): main-conversation-grade Blocks structure, per-turn usage tails, reconnect banner
-- ⚙️ **Workspace path fence toggle** (#458): a new `workspaceFence` declarative settings key with a one-click off affordance and guidance on 403 error surfaces
+- ⚙️ **Workspace fence and external previews**: `workspaceFence` still protects tree browsing, save, rename, delete, and upload operations; explicitly opened absolute files may be previewed read-only outside the workspace (text, media, and HTML), with clear filesystem errors for missing or unreadable files
 
 **⚡ Performance**
 

dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-better-sidebar",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "main": "./lib/index.js",
   "description": "VSCode 风格右侧侧边栏：文件资源管理器 / 编辑器 / 终端 / Git / 浏览器，按会话隔离。暴露服务供其他插件注册侧边栏页面和文件预览器",
   "engines": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-better-sidebar",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "DSH web plugin: a VSCode-like right sidebar (explorer / editor / terminal / git / browser), isolated per conversation session. Exposes a service for other plugins to register sidebar tabs and file viewers.",
   "type": "module",
   "repository": {

src/client/service.ts

@@ -465,7 +465,7 @@ export function matchUrlTarget(tabs: readonly TabDescriptor[], url: URL): TabDes
  * The plugin version this service instance reports. Keep in lockstep with
  * `package.json`'s version — `tests/service.spec.ts` asserts the pair.
  */
-export const SIDEBAR_SERVICE_VERSION = '0.18.0'
+export const SIDEBAR_SERVICE_VERSION = '0.18.1'
 
 /**
  * Monotonic capability list consumers use to gate new API usage (features

src/index.ts

@@ -32,7 +32,7 @@ import {
 import { parentOf, requireAbsolute, listDirectory, rootLabel } from './fs-tree.ts'
 import { resolveSessionPath } from './session-path.ts'
 import { writeWorkspaceUpload } from './fs-operations.ts'
-import { ensureWorkspacePath, ensureWorkspaceWritePath } from './path-security.ts'
+import { ensurePreviewPath, ensureWorkspacePath, ensureWorkspaceWritePath } from './path-security.ts'
 import { searchFiles } from './fs-search.ts'
 import { decodeHtmlUrl } from './html-route.ts'
 import { extractFrameAncestors } from './browser-probe.ts'
@@ -349,7 +349,7 @@ function buildApi(
       // child-repo path is relative to the selected repoRoot, not the session
       // cwd; thread it so the path resolves inside the authorized workspace.
       const selected = selectedRepoOf(payload)
-      const path = await ensureWorkspacePath(cwd, await resolveGitPath(cwd, requireString(payload, 'path'), selected), fenceEnabledOf(getSettings))
+      const path = await ensurePreviewPath(cwd, await resolveGitPath(cwd, requireString(payload, 'path'), selected))
       const { content, truncated, binary, size, head } = await readText(path, resolved.readLimit)
       if (binary) return { kind: 'binary', size, truncated, head }
       return { kind: 'text', content, truncated }
@@ -929,7 +929,7 @@ export function apply(ctx: Context, config?: SidebarConfig): void {
         const raw = url.searchParams.get('path')
         if (sessionId === null || raw === null) throw new SidebarError('bad-request', 'sessionId and path are required')
         const cwd = await sessionCwdOf(ctx, sessionId, url.searchParams.get('cwd') ?? undefined)
-        const path = await ensureWorkspacePath(cwd, raw, fenceEnabledOf(() => settingsFace))
+        const path = await ensurePreviewPath(cwd, raw)
         const info = await stat(path)
         if (!info.isFile() || info.size > resolved.mediaLimit) {
           throw new SidebarError('fs-error', 'not a file or too large', 400)
@@ -988,7 +988,7 @@ export function apply(ctx: Context, config?: SidebarConfig): void {
         // real-path guard, with the same semantics as the media route's
         // fallback.
         const cwd = await sessionCwdOf(ctx, sessionId)
-        const absolute = await ensureWorkspacePath(cwd, path, fenceEnabledOf(() => settingsFace))
+        const absolute = await ensurePreviewPath(cwd, path)
         const info = await stat(absolute)
         if (!info.isFile() || info.size > resolved.mediaLimit) {
           throw new SidebarError('fs-error', 'not a file or too large', 400)

src/path-security.ts

@@ -42,6 +42,15 @@ export async function ensureWorkspacePath(cwd: string, target: string, fence = t
   return realTarget
 }
 
+/**
+ * Resolve one existing file selected for read-only preview. Explicit absolute
+ * files may live outside the session workspace; canonicalization and readable
+ * filesystem errors remain identical to workspace-scoped reads.
+ */
+export async function ensurePreviewPath(cwd: string, target: string): Promise<string> {
+  return ensureWorkspacePath(cwd, target, false)
+}
+
 /**
  * Validate a write destination, including destinations that do not exist yet.
  * Existing targets are resolved to catch symlinks; missing targets are checked

tests/smoke.spec.ts

@@ -665,14 +665,14 @@ describe('session cwd resolution over the API route', () => {
     expect(value.value?.content).toContain('runGit')
   })
 
-  it('rejects repo-root-relative fs.read paths outside a nested session workspace', async () => {
+  it('previews repo-root-relative fs.read paths outside a nested session workspace', async () => {
     const route = mount({
       sessions: {
         get: () => ({ header: { cwd: join(process.cwd(), 'src') } }),
       },
     })
     const result = await invoke(route, 'fs.read', { sessionId: 's-sub', path: 'package.json' })
-    expect(result).toMatchObject({ ok: false, status: 403, error: { code: 'forbidden' } })
+    expect(result).toMatchObject({ ok: true, value: { kind: 'text' } })
   })
 
   it('rejects fs.tree paths outside the session workspace', async () => {
@@ -692,7 +692,7 @@ describe('session cwd resolution over the API route', () => {
     }
   })
 
-  it('rejects fs.read paths outside the session workspace', async () => {
+  it('reads explicit files outside the session workspace for preview', async () => {
     const root = mkdtempSync(join(tmpdir(), 'dsh-sidebar-fs-security-'))
     const workspace = join(root, 'workspace')
     const outside = join(root, 'outside')
@@ -703,7 +703,7 @@ describe('session cwd resolution over the API route', () => {
     try {
       const route = mount({ sessions: { get: () => ({ header: { cwd: workspace } }) } })
       const read = await invoke(route, 'fs.read', { sessionId: 'security', path: outsideFile })
-      expect(read).toMatchObject({ ok: false, status: 403, error: { code: 'forbidden' } })
+      expect(read).toMatchObject({ ok: true, value: { kind: 'text', content: 'secret' } })
     } finally {
       rmSync(root, { recursive: true, force: true })
     }
@@ -724,7 +724,7 @@ describe('session cwd resolution over the API route', () => {
     }
   })
 
-  it('rejects media and HTML reads through a workspace symlink', async () => {
+  it('serves explicit media and HTML previews through an external symlink', async () => {
     if (!canCreateSymlink) return
     const root = mkdtempSync(join(tmpdir(), 'dsh-sidebar-route-symlink-security-'))
     const workspace = join(root, 'workspace')
@@ -745,10 +745,8 @@ describe('session cwd resolution over the API route', () => {
       // platform (a Windows drive path needs the leading slash separator
       // that a naive join-without-separator drops).
       const htmlResult = await invokeGet(html, encodeHtmlUrl('security', join(workspace, 'link', 'secret.html')))
-      expect(mediaResult).toMatchObject({ status: 403 })
-      expect(JSON.parse(mediaResult.body)).toMatchObject({ ok: false, error: { code: 'forbidden' } })
-      expect(htmlResult).toMatchObject({ status: 403 })
-      expect(JSON.parse(htmlResult.body)).toMatchObject({ ok: false, error: { code: 'forbidden' } })
+      expect(mediaResult).toMatchObject({ status: 200, body: 'not an image' })
+      expect(htmlResult).toMatchObject({ status: 200, body: '<p>secret</p>' })
     } finally {
       rmSync(root, { recursive: true, force: true })
     }
@@ -784,7 +782,7 @@ describe('session cwd resolution over the API route', () => {
     }
   })
 
-  it.skipIf(!canCreateSymlink)('rejects fs.read through a workspace symlink', async () => {
+  it.skipIf(!canCreateSymlink)('previews fs.read through a workspace symlink', async () => {
     const root = mkdtempSync(join(tmpdir(), 'dsh-sidebar-fs-symlink-security-'))
     const workspace = join(root, 'workspace')
     const outside = join(root, 'outside')
@@ -795,7 +793,7 @@ describe('session cwd resolution over the API route', () => {
       symlinkSync(outside, join(workspace, 'link'))
       const route = mount({ sessions: { get: () => ({ header: { cwd: workspace } }) } })
       const read = await invoke(route, 'fs.read', { sessionId: 'security', path: join(workspace, 'link', 'secret.txt') })
-      expect(read).toMatchObject({ ok: false, status: 403, error: { code: 'forbidden' } })
+      expect(read).toMatchObject({ ok: true, value: { kind: 'text', content: 'secret' } })
     } finally {
       rmSync(root, { recursive: true, force: true })
     }
@@ -989,11 +987,14 @@ describe('side card settings routes', () => {
     writeFileSync(join(outside, 'secret.txt'), 'global instructions')
     try {
       const route = mountWithSettings(createFakeSettings())
-      // Default (fence on): the outside read is refused as usual…
-      const refused = await invoke(route, 'fs.read', { sessionId: 'fence', cwd: workspace, path: join(outside, 'secret.txt') })
-      expect(refused).toMatchObject({ ok: false, error: { code: 'forbidden' } })
-      // …then the settings-page switch (or the fence notice's one-click off)
-      // disarms every fs route for paths outside the workspace.
+      // Read-only previews accept explicit external files while tree and write
+      // operations remain fenced until the existing global switch is off.
+      const preview = await invoke(route, 'fs.read', { sessionId: 'fence', cwd: workspace, path: join(outside, 'secret.txt') })
+      expect(preview).toMatchObject({ ok: true, value: { kind: 'text', content: 'global instructions' } })
+      const fencedTree = await invoke(route, 'fs.tree', { sessionId: 'fence', cwd: workspace, path: outside })
+      expect(fencedTree).toMatchObject({ ok: false, error: { code: 'forbidden' } })
+      const fencedWrite = await invoke(route, 'fs.write', { sessionId: 'fence', cwd: workspace, path: join(outside, 'written.txt'), content: 'blocked' })
+      expect(fencedWrite).toMatchObject({ ok: false, error: { code: 'forbidden' } })
       const off = await invoke(route, 'settings.update', { patch: { workspaceFence: false } })
       expect(off.ok).toBe(true)
       const read = await invoke(route, 'fs.read', { sessionId: 'fence', cwd: workspace, path: join(outside, 'secret.txt') })