外观
隐私与威胁模型
MacFlare 把选择的设备状态发布到公网。知道部署地址的任何人都可以读取 /api/now、音乐／应用／设备分类接口和 /api/badge.svg，包括搜索服务、监测机器人以及可能长期记录状态的第三方。随机部署域名和 CORS 都不是访问控制。
数据范围
| 数据 | 用途 | 边界 |
|---|---|---|
| 前台应用名称 | 显示当前正在使用的应用 | 不读取窗口标题、文档名、路径或网页 URL |
| 正在运行的 GUI 应用名称 | 展示已打开的应用 | 不上传完整进程表、命令行或 PID；可关闭 |
| Music 播放状态、歌名、歌手 | 显示正在听的内容 | 仅 Music.app；可关闭；不上传音频 |
| 电量、充电、供电来源 | 展示设备电池状态 | 不上传序列号或电池历史 |
| 系统负载 | 展示当前负载概况 | 负载平均值不是 CPU 使用率百分比 |
| 快照时间 | 判断新鲜度 | 公开时间可能被用于推断作息 |
敏感应用过滤在本机执行。屏蔽名单匹配到前台应用时使用通用名称 System，运行应用列表也过滤敏感条目。名称屏蔽可能受应用改名、本地化和未列出的敏感软件影响，应结合 配置 检查实际预览；对隐私要求较高时关闭应用列表或整个应用采集。
信任边界
| 边界 | 采取的措施 | 仍然存在的风险 |
|---|---|---|
| Mac → Worker | HTTPS 与独立 Bearer 令牌；本机过滤 | Mac 被入侵、配置文件泄漏或令牌被窃取时可伪造状态 |
| 公网 → Worker | 接收鉴权、字段校验、体积限制、服务器控制的 TTL | 无专用配额保护；公开读取可能消耗平台配额 |
| Worker → KV | 只覆盖当前键并设置 TTL | 平台缓存、一致性与平台自身数据处理受 Cloudflare 控制 |
| Worker → 页面 | 固定 JSON/SVG 类型、SVG 文本转义 | 网站自身若用 innerHTML 插入字段仍可引入漏洞；应使用 textContent |
| 公网 → Mac | 没有入站监听、远程命令或回连能力 | 单向架构减少攻击面，不等于消除所有安全风险 |
INGEST_TOKEN 是发送状态的凭据，不是 Cloudflare 账户 API Token。前端、GitHub README、Issue、截图和 Git 历史都不应包含它。读取设备状态时，前端调用公开的 GET /api/now，不要把 /api/update 的令牌打包进浏览器代码。
首页歌曲封面
快照仍新鲜、Music 为 playing 或 paused，且歌名与歌手齐全时，访客浏览器直接向 Apple iTunes Search API 发起 GET：term=歌名+歌手、entity=song、country=us、limit=5。Apple 会收到这些公开曲目信息及访客的网络请求，包括连接 IP；查询不发送电池、应用、负载等其他设备指标或任何令牌。Apple 搜索参数说明
页面仅为可信匹配显示返回的 artworkUrl100，图片由访客浏览器向 Apple 图片 CDN 请求；点击封面会打开 Apple 的歌曲页面。美国商店无可信匹配时不盲选其他歌曲，搜索或图片失败只显示占位，不影响文字状态。收到 stopped 或快照过期时立即撤掉封面。Apple 搜索结果字段
查询缓存仅在当前浏览器页面的内存中：成功结果保留 1 小时，普通查询失败或无可信匹配保留 5 分钟，最多 50 条；取消的请求不缓存。MacFlare 不将其写入本地持久存储或 Cloudflare KV；浏览器及 Apple 自身的缓存遵循各自策略。此功能不改变 /api/now 协议，也不把封面字段写入设备快照。
音乐 API 封面查询
调用 /api/music 时，Worker 从当前新鲜快照读取音乐状态，必要时代表调用者向 Apple iTunes Search API 查询公开歌名与歌手。固定使用美国商店、歌曲类型和最多 5 个候选；严格匹配后只返回经过检查的 Apple HTTPS 封面与歌曲 URL。该搜索由 Worker 发起，不发送设备电量、负载、应用列表或接收令牌。
服务端缓存只保存公开目录的匹配结果，不保存播放状态、设备快照或历史记录，也不写 KV。成功结果缓存 1 小时，未匹配或失败结果缓存 5 分钟；每个运行实例最多保留 50 条内存记录，并可复用所在边缘节点的 Cache API 结果。这些缓存可能提前淘汰，不承诺跨地区共享；公开目录结果可能晚于设备快照 TTL 过期，不能据此判断设备仍在线。
API 调用者将 artwork_url 放入图片元素后，访客浏览器向 Apple 图片 CDN 发起请求，Apple 会收到对应图片请求和访客网络信息；点击 track_url 会访问 Apple 的歌曲页面。封面字段可为 null，无需为显示文字状态自行补搜。
首页仍按 浏览器封面流程 直接查询 Apple，不额外请求 /api/music。两条路径的缓存彼此独立，都不改变 /api/now 或本机上报字段。
首页应用图标
首页优先使用仓库中的原生 PNG。维护者在开发阶段从配置名单内的已安装应用导出图标；PNG 和应用名称、别名构成的有限清单会进入 Git 并公开发布。这不是实时运行列表，但可能透露维护者选用的软件；不要导出私有应用的图标或名称。
访客从同一 Cloudflare 站点的 /app-icons/<id>.png 加载原生图标，不向第三方图标服务查询。公开 /api/icons 和 /api/icons/<id>.png 提供相同清单与图片，Mac 离线或上报失败也仍可读取。Cloudflare 会收到图片请求及访客网络信息；图标请求不携带电池、负载、曲目、完整运行列表或任何令牌。隐私屏蔽后的 System 在状态页使用占位。
若维护者额外启用 macOSicons，同步时搜索 API 只接收配置中的固定应用名与鉴权请求，不接收逐个访客的实时运行列表。Key 和生成缓存不进入 Git，Key 也不进入浏览器。只有使用该补充来源时，浏览器才向图标 CDN 请求原始 lowResPngUrl；CDN 可看到访客网络信息和对应图片请求，可能由此推断展示的应用。
原生图标是随部署保留的静态资源，不随设备快照 TTL 删除；需要移除时修改仓库并重新部署，已经公开的 Git 历史或他人副本不会自动撤回。macOSicons 响应缓存另有最多 30 天的有效期，到期不再展示。两种来源都不访问 KV，也不增加 /api/now 字段。导出、署名与使用边界
保留与删除
服务只保留一个当前快照，写入时指定服务端过期时间（eco 默认 180 秒，realtime 60 秒）；本项目不建立历史表。停止 Agent 后，新鲜度检查会将过期状态视为离线。TTL 不代表已经抹除请求经过的所有系统日志、备份或第三方缓存，更不能撤回别人已下载的数据。Cloudflare 的账户级日志、观测和保留策略应由部署者另行核对。
减少公开范围时，先调整本机配置，再推送一次让新快照覆盖旧快照；仅关闭采集程序会等到既有状态过期。遇到泄漏先停止采集并轮换 Secret，具体步骤见 安全策略。
macOS 授权
Music 自动化可能需要用户在 macOS 的系统弹窗中允许。可在“系统设置 → 隐私与安全性 → 自动化”检查运行脚本的终端或宿主是否获准控制 Music。脚本不能代替用户授予系统权限；不要通过关闭系统保护来解决。终端手动运行成功也不自动证明 launchd 执行上下文获准，应分别核验。Apple 自动化权限说明
项目不要求屏幕录制、读取浏览器历史或完整磁盘访问权限。权限被拒绝时应保持该采集项不可用，其他独立指标仍可以继续上报。