dsh-plugin-folder-trust
Verifieddsh-plugin-folder-trust · v0.2.4 · MIT · Web UI
Windows: when a new workspace folder is added, ask once whether to trust it, then grant the NTFS rights DSH's workspace-write sandbox needs. When the folder is owned by another machine's account, the repair asks Windows for one approved UAC elevation inst
Install
dsh plugin add dsh-plugin-folder-trust Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme
dsh-plugin-folder-trust
Windows 专用:新增工作区后,先问一次「信任此文件夹吗?」,点「信任文件夹」就地为该目录补齐 DSH workspace-write 沙箱所需的那一条 NTFS 权限,之后工作区里的受限 shell 才能写入,不会再每次都要在对话里提权。
为什么需要它
DSH 在 Windows 上把「工作区内修改」实现成:受限令牌 + 按工作区路径派生的 SID 写权限 ACE + Low 完整性标签,全部在一次 SetNamedSecurityInfoW 里落盘。这一次调用要求当前账户对工作区根目录同时有 WRITE_DAC(改权限)和 WRITE_OWNER(改属主/完整性标签)。缺任何一个,DSH 自己就补不上授权,于是每条受限命令在启动前就被拒绝(SetNamedSecurityInfoW failed (Win32 5): grantWrite(...)),用户只能切「完全权限」继续。
本插件把这一步变成一次点击:
- 监听持久化工作区注册表(
ctx.workspaceRegistry.list()),插件启动之后新增的工作区才参与判定; - 对新目录只读探测两个权利(真实令牌,不提权);
- 权利齐全 → 直接记住,不打扰;
- 缺权利 → 浏览器弹出模态「信任此文件夹吗?」,两个选择:
- 信任文件夹:给你的账户补一条完全控制 ACE,再按 DSH 的算法把能力 SID 的 ACE 与 Low 标签铺进已有子树,校验后记住该路径;
- 忽略:只把该路径记进
state.json的dismissed,不会再为这个文件夹弹窗,也不改动任何权限。弹窗里明说了后续代价:在「工作区内修改」模式下 DSH 仍无法为它准备写权限,之后每次需要在其中写入时沙箱都会再次请求授权(或临时切到「完全权限」)。
属主不是本机账户时:一次 UAC 授权
Windows 只给所有者本人隐式 WRITE_DAC。从另一台电脑整包拷过来的目录,DACL 里带的是那台机器的账户 SID(本机解析不出来),当前账户通常只靠 Authenticated Users 拿到「修改」——能改文件、不能改权限,于是任何非提权的补权限都会在 SetNamedSecurityInfoW 上返回 5。这时只有一种合法出路:让 Windows 问用户一次,用你批准过的管理员令牌去改。
插件因此分组处理(lib/status.mjs 的 ownerNeedsElevation,判定来自探测里的 ownerKind):
ownerKind |
含义 | 修复方式 |
|---|---|---|
current |
属主就是你 | 直接补 ACE,不弹窗 |
local-other / system |
本机其它账户 / SYSTEM、内置组 | 缺少 WRITE_DAC 时走 UAC |
foreign |
SID 在本机解析不出来(从别的电脑拷来) | 走 UAC |
走 UAC 时弹窗先说明原因(「这个文件夹来自另一台电脑:所有者 … 不属于本机账户」),按钮变成「以管理员身份修复」;点击后 lib/elevate.ps1 用 Start-Process -Verb RunAs 拉起同一份 propagate.ps1,一次授权同时完成:补当前账户完全控制、写能力 SID 与 Everyone deny、写 Low 标签、铺进已有子树。用户点「否」时不会做任何改动,并明确回报“已取消”。UAC 窗口本身就是审计记录——插件不会静默提权,也不会在取消后重试。
输入框里的权限检查
DSH 的工作区行「…」菜单没有插件扩展点(rename/delete 是 dsh-client-ui-workspace 里写死的数组,只有会话行菜单是 slot),所以检查入口放在输入框右侧的控制行,紧挨着 pwsh7 那个 chip:
- 正常时不显示:当前会话所属工作区的权限齐全,控制行里没有这个按钮;
- 异常时显示「工作区权限异常」:外框写死为 20px 高、108px 宽(与 pwsh7 的 20px 控制行同高、同圆角),不依赖旁边有没有 pwsh7;
- 点开后只列出当前工作区的三组状态和「修复权限」,不再把其它工作区摊在一起。
当前工作区是这样认出来的:conversation.input.right 是 session 作用域的插槽,宿主会把 sessionId 和一组快照 hook 作为标准 props 交给组件(不需要 inject,重复注入反而会撞上标准 prop)。按顺序取第一个拿得到的目录:
useSessions((s) => s.byId[sessionId]?.cwd)——会话列表摘要里的工作区目录,DSH 自己的输入框也是这么读的(useSession()返回的是快照,没有cwd,别用它);useWorkspaces(...)里sessionIds含该会话的那一行的path;- 浏览器侧
workspaces服务的快照(侧栏工作区树读的同一个 store),作为兜底; - 宿主报告行若带
sessionIds(宿主重载后才有),再按它认领一次。
全都拿不到时按钮保持隐藏,不猜别的工作区。判定用的 issues / needsRepair 由宿主算好放进报告行;宿主还没重载时,浏览器按 permissions 自己推同样的结论(issuesOf() 的兜底分支),所以只刷新页面也能完整工作。
设置页:所有工作区的权限
「设置 → 工作区权限」是同一份报告的完整体,列出每个已注册工作区:
- 账户能否改权限 / 改所有者(缺哪个就写哪个);
- 沙箱写入授权是否已落在根目录;
- 一级子文件夹里有几个已继承授权(x/y);
- 包含 %TEMP% 的工作区标记为不可用。
有问题的行带「修复权限」:补当前账户完全控制 → 把授权与 Low 标签按名字铺进已有子树 → 重新探测并刷新该行状态。修复只对已注册工作区生效。页面右上角「重新检测」会绕过 15 秒缓存重新探测。
两处入口共用 lib/status.mjs 的判定(issues / needsRepair 由宿主在报告行里算好),所以「什么算需要修复」不存在两份实现。
想撤销「忽略」:从 state.json 的 dismissed 里删掉该路径(重启后生效),再重新加一次工作区即可重新提示。
组成
| 文件 | 职责 |
|---|---|
index.js |
宿主入口:注入 webServer,等 workspaceRegistry 就绪后启动轮询,注册路由 |
lib/service.mjs |
工作区判定、待信任队列、~/.dsh/folder-trust/state.json 持久化、报告行(含 issues / needsRepair / sessionIds) |
lib/status.mjs |
纯判定:路径归一化、问题码、是否需要修复、按路径找行 |
lib/acl.mjs |
探测 WRITE_DAC/WRITE_OWNER 与属主分类;缺则补完全控制 ACE 并复读校验;属主不是本机账户时走提权助手(子进程,输出走临时文件、不占用管道) |
lib/elevate.ps1 |
只在用户点击时用 Start-Process -Verb RunAs 请求一次 UAC,随后以管理员身份运行 propagate.ps1;取消与失败分别回报,不重试 |
lib/routes.mjs |
GET /folder-trust/state、POST /folder-trust/trust、POST /folder-trust/dismiss、GET /folder-trust/report、POST /folder-trust/repair、GET/POST /folder-trust/debug;只接受待办路径或已注册工作区,浏览器无法让宿主改任意目录 |
client.js |
shell.overlay 的信任模态(2 秒轮询)、输入框的权限检查(15 秒轮询)、settings.section 的「工作区权限」页 |
test/ |
ACL 探测/授权幂等性、工作区判定与拒绝持久化、判定规则 |
POST /folder-trust/debug 只接收浏览器上报的插槽 props 摘要(data-slot 诊断用),GET 返回它和轮询状态;两者都不改任何权限。
行为边界
- 子目录会被一起铺开:DSH 用目录句柄写入授权和 Low 标签,句柄写入不触发继承,所以工作区根可用而"早就存在"的子目录不可用。插件按 DSH 的算法自己派生同一个 S-1-4 SID(sha256(规范化路径) 的两段 30 位),按名字重写根目录的 DACL/SACL,让 Windows 把 ACE 与标签递归铺到整棵已有子树,并在子目录上抽样校验;已信任的路径启动时也补做一次,结果记在
state.json的propagated。 - 只在用户点头时提权:正常路径用 DSH 自己的令牌补权限(不提权)。目录连 WRITE_DAC 都没有(属主是别的机器的账户、SYSTEM,或显式拒绝)时,修复会请求一次 UAC 授权,由你点「是」才执行;点「否」不改动任何东西并明确回报取消。取消后不会自动重试。
- 工作区包含
%TEMP%(例如直接拿C:\Users\<你>当工作区)时沙箱结构性不可用:信任弹窗只说明原因、不给「信任」,检查按钮与设置页把它标为不可用且不提供修复。 - 授权只落在工作区子树,不改文件内容、不改属主、不删任何 ACE;
state.json记录已信任/已拒绝/已铺开的路径。 - 忽略与受信互斥:信任或修复成功后,路径会从
dismissed移出——同一路径不会既「已忽略」又「已受信」。旧版本留下的矛盾状态(两个集合都有)会在下一次启动分类到trusted时自动清掉并回写state.json,不需要手改文件。 - 标签写入不需要提权:写 Low 完整性标签要的是对象上的 WRITE_OWNER,而修复写进去的完全控制已经包含它(所有者本身还有隐式 WRITE_DAC),所以普通账户能直接写完;子目录如果只有 Modify,修复会在写标签前临时借一个
TakeOwnershipACE,写完立刻收回。只有连这个权利都没有(属主是别人、或显式拒绝)时才需要管理员授权。 - 禁用继承(protected DACL)也能修:
Set-Acl在已经带 protected 标志的 DACL 上会连带写 SACL,非管理员会报SeSecurityPrivilege——即使目录属于自己。现在 DACL 写入只走SetNamedSecurityInfoW的 DACL 位并保留 protected 标志;子目录确实修不了时会记录失败并让修复返回失败(报告继续显示children),不再静默报“修复完成”。 - 解释器优先 PowerShell 7:helper 脚本用
Get-Acl读、SetNamedSecurityInfoW只写 DACL(5.1 与 7 都有),Low 标签那段也是 P/Invoke,两种解释器都跑得通,所以按「pwsh(7)→ Windows PowerShell 5.1」的顺序挑一个,FOLDER_TRUST_POWERSHELL可钉住指定可执行文件。早先硬编码powershell.exe,是因为脚本用了 .NET Framework 专有的DirectoryInfo.GetAccessControl()——7.6(.NET 10)里没有这个方法,那是 5.1 成为硬依赖的唯一原因。 - 5.1 会拿到自己的模块路径:5.1 若继承 PowerShell 7 的
PSModulePath,会把Microsoft.PowerShell.Security解析到 7 的程序集上、加载失败,于是Get-Acl直接报「成员已存在」——恰恰在「没有自己的 PowerShell 7、但宿主跑在 7 之下」的机器上把回退打掉。因此 spawn 5.1 时把PSModulePath重建成它的三个目录(用户、机器、System32),7 则保持继承。 - 提权只认全局解释器:跨 UAC 边界时裸
pwsh.exe没有路径给 ShellExecute,用户目录里的便携版(例如插件安装在 AppData 下的那份)还可能属于 UAC 切换到的另一个管理员账户。所以提权固定用绝对路径的机器级 PowerShell:装了系统级 7 就用它,否则用 System32 的 5.1。启动参数按需加引号,用户目录带空格(C:\Users\John Smith)也不会被拆开。 - 是否真的可用看标签,不只看授权:受限 shell 的令牌是 Low 完整性 + 写受限,缺 Low 标签时能力 SID 的 ACE 是空的。检查项里因此包含标签(
lowLabel),修复也只有在标签真正写上之后才算成功。 - 只影响 Windows;其他平台该行不会被插入。
安装 / 卸载
profile 里把它加进 dsh.profile.bundles 与依赖,并在 profiles/desktop/node_modules 建指向本包的链接即可。卸载时删掉这两处(package.json、bundles 里的 dsh-plugin-folder-trust)并删除链接,刷新页面后插件不再加载。
改了宿主半侧(index.js、lib/*.mjs)后需要重启 DSH(或重新加载该插件)才生效;只改 client.js 时刷新页面即可。