# 安全说明

## ⚠️ 这是一个破坏性工具

disk-butler 的 `Invoke-Cleanup.ps1` 在加了 `-Execute` 之后会**真正删除文件**，不进回收站。
请先读下面的安全模型再使用。

---

## 安全模型

设计上是**四层防护**，每层都假设上一层可能失效：

### 第 1 层：扫描器永不删除

`Find-Junk.ps1` 只产出 JSON 计划（含安全等级、体积、理由）。它没有任何删除代码路径。

### 第 2 层：执行器默认预演

`Invoke-Cleanup.ps1` 不传 `-Execute` 时**只打印将要做什么**，不做任何改动。
必须先看到预演结果，才可能执行。

### 第 3 层：双层校验（纵深防御）

安全规则在**扫描时**和**执行时**各校验一遍。这意味着：

- 过期的计划不会因为"当时判断过"就放行
- **被篡改的计划也删不掉环境变量锚定的位置**——执行时会重新检查

校验规则：

| 条件 | 行为 |
|---|---|
| 目标是环境变量指向的路径 + 整体删除 | **拒绝** |
| 目标是环境变量指向的路径 + 按时间清理 | 允许，但安全等级强制降为 `Confirm` |
| 目标内含 `backup` / `recover` / `备份` / `恢复` 子目录 | **拒绝**，除非显式 `-Force` |
| 需要管理员权限但当前无权限 | 跳过并提示 |
| 目标已不存在 | 跳过 |

### 第 4 层：隔离区（可选，但推荐）

`-Quarantine` 把目标移进**同盘**隔离区而不是删除：

```powershell
.\skills\disk-butler\scripts\Invoke-Cleanup.ps1 -Plan plan.json -Execute -Safety Safe -Quarantine
```

- 可 `-RestoreQuarantine -Batch <批次号>` 恢复
- 可 `-PurgeQuarantine -OlderThanDays 7` 观察够了再彻底删
- **⚠️ 隔离 ≠ 释放空间**：空间要等 purge 才回来

---

## 已知限制

这些不是漏洞，是当前设计有意留下的边界：

- **机器判断不了"重要性"**。环境变量、备份子目录这类机械事实能自动查，"这个目录对业务是否关键"只有人知道。
- **原子性有限**。按时间清理是一批一个文件地删除；中途失败会留下部分结果。隔离模式下这一点更可控。
- **跨盘迁移不是原子的**。`Move-Cache.ps1` 会先复制并校验文件数与字节数，一致才删源；但复制与删除之间若断电，可能出现两边都有内容（源目录不会被删，可手动清理）。
- **需要管理员的目标会静默跳过**（会在输出里说明），不会提权。

## 不要把凭据放进 issue

报告问题时，日志里可能有路径。请先确认没有把 `auth.json`、token、API key 之类的内容贴出来。

---

## 报告安全问题

如果发现的是**安全漏洞**（例如绕过安全校验、路径穿越导致误删未预期位置、计划文件可被构造成越权删除），请**不要开公开 issue**。

用 GitHub 的私有漏洞报告：仓库 **Security** 标签页 → **Report a vulnerability**。
或者直接给维护者发 GitHub 私信（[@Aurirlk](https://github.com/Aurirlk)）。

请附上：

1. 你的环境（Windows 版本、PowerShell 版本 `$PSVersionTable.PSVersion`）
2. 最小复现步骤（**请在测试目录上复现，不要用真实数据**）
3. 涉及的文件与命令
4. 期望行为 vs 实际行为

普通 bug（功能不对、显示错误、崩溃）请直接开 issue，附上 `Test-SkillHealth.ps1 -Deep` 的输出。