# 🔐 安全说明

## 为什么需要提供密码？

OpenClaw with Apple 需要连接你的 iCloud 服务来实现日历读写、提醒事项同步、备忘录同步、健康数据分析等功能。Apple 不提供第三方 API Token 机制，因此必须使用你的凭证进行认证。

| 凭证类型 | 用途 | 风险等级 |
|----------|------|---------|
| 应用专用密码 | 仅能操控 CalDAV 日历，无法访问其他数据 | 低 |
| Apple ID 邮箱 + 主密码 | 访问 iCloud Drive、提醒事项、备忘录、照片、健康等 | 较高 |

---

## 你的密码如何被使用？

### 1. 密码不落盘

- 密码仅通过环境变量 (`ICLOUD_USERNAME` / `ICLOUD_PASSWORD`) 在内存中临时存在
- **不会被写入任何配置文件、日志文件或数据库**
- 登录成功后，密码引用会被主动清除（`del password`）

### 2. 登录后只保存 Session Token

- 首次登录（含 2FA 验证）成功后，pyicloud 库会将 **session token 和 cookies** 缓存到 `~/.pyicloud/` 目录
- 后续所有操作复用此 session，**不再需要密码**
- Session 过期后需重新登录

### 3. 应用专用密码的隔离性

- 应用专用密码由 Apple 生成，**仅能访问 CalDAV 日历协议**
- 无法用它登录 iCloud 网页、访问照片、文件或任何其他服务
- 你可以随时在 [appleid.apple.com](https://appleid.apple.com) 撤销该密码

---

## 安全措施

| 措施 | 说明 |
|------|------|
| 环境变量传递 | 密码通过 `export` 设置在 shell 环境中，不写入文件 |
| Session 缓存 | 登录后只存 token，不存密码 |
| 2FA 双重认证 | 每次新登录都需要 iPhone/iPad/Mac 上确认 6 位验证码 |
| 缓存目录权限 | `~/.pyicloud/` 目录权限为 `0o700`，仅当前用户可读 |
| 主动清除 | 登录完成后代码主动 `del password` 释放内存引用 |
| 可随时撤销 | 应用专用密码可在 Apple ID 页面一键撤销 |

---

## 风险提示

1. **环境变量在进程中可见**：同一用户的其他进程理论上可以读取环境变量。如果你在共享服务器上使用，请注意这一点
2. **Session 文件安全**：`~/.pyicloud/` 下的 session 文件如果被他人获取，可以在 session 有效期内访问你的 iCloud 服务。请确保该目录权限正确
3. **AI 对话记录**：你在对话中发送的密码会存在于对话历史中。建议在配置完成后，清理包含密码的对话记录

---

## 最佳实践

1. **优先使用应用专用密码**：如果你只需要日历功能，只提供应用专用密码即可，无需暴露主密码
2. **定期轮换**：建议每隔几个月在 [appleid.apple.com](https://appleid.apple.com) 重新生成应用专用密码
3. **用完即撤**：如果不再使用本项目，去 Apple ID 页面撤销对应的应用专用密码
4. **检查 Session**：定期运行 `python scripts/icloud_auth.py status` 确认 session 状态，过期后重新登录即可
5. **不要在公共环境使用**：避免在共享电脑或公共服务器上输入 Apple ID 主密码