外观
隐私与威胁模型
MacFlare 把选择的设备状态发布到公网。知道部署地址的任何人都可以读取 /api/timeline、/api/now、音乐／应用／设备分类接口和 /api/badge.svg，包括搜索服务、监测机器人以及可能长期记录状态的第三方。随机部署域名和 CORS 都不是访问控制。
数据范围
| 数据 | 用途 | 边界 |
|---|---|---|
| 前台应用名称 | 显示当前正在使用的应用 | 不读取窗口标题、文档名、路径或网页 URL |
| 正在运行的 GUI 应用名称 | 展示已打开的应用 | 不上传完整进程表、命令行或 PID；可关闭 |
| Music 播放状态、歌名、歌手与可选封面／歌曲 URL | 显示正在听的内容 | 仅 Music.app；可关闭；不上传音频或封面文件 |
| 电量、充电、供电来源 | 展示设备电池状态 | 不上传序列号；buffered 可含窗口内电量变化 |
| 系统负载 | 展示当前负载概况 | 负载平均值不是 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/timeline 或 GET /api/now，不要把 /api/batch 或 /api/update 的令牌打包进浏览器代码。
首页歌曲封面
首页优先使用当前有效播放切片中由 Mac 上报的 music.artwork_url 与 music.track_url。访客浏览器向 Apple 图片 CDN 加载封面，点击链接访问 Apple 歌曲页面；Apple 会收到这些图片／网页请求和访客网络信息。停止播放或快照过期时撤掉封面，查询或图片失败不影响歌名和歌手。
缺少有效上报 URL 时，页面保留浏览器查询，以兼容旧 Agent 或没有匹配结果的快照。只有新鲜的 playing／paused 状态且歌名歌手齐全时才查询：GET 参数为 term=歌名+歌手、entity=song、country=us、limit=5。此时 Apple 还会收到公开曲目信息和访客搜索请求，包括连接 IP；不发送电池、应用、负载或令牌。美国商店无可信匹配时不盲选其他歌曲。Apple 搜索参数
浏览器兼容查询的缓存只存在当前页面内存：成功 1 小时、普通失败或无匹配 5 分钟，最多 50 条；取消请求不缓存，不写本地持久存储或 KV。浏览器与 Apple 自身的 HTTP 缓存遵循各自策略。首页只轮询 /api/timeline，不为封面额外请求 /api/music。Apple 封面和歌曲字段
音乐 API 与封面上报
Mac Agent 使用系统 curl 向 Apple iTunes Search API 查询公开歌名与歌手，并通过原生 JXA 严格匹配美国商店的歌曲结果。Apple 收到 Mac 的搜索请求与网络信息；查询不携带接收令牌、设备电量、负载或应用列表，不下载封面图片。匹配成功后，安全 HTTPS URL 随现有快照一起上传并保存在同一个 KV 键中，不增加推送或写入次数。
v1 快照模式的本机私有 artwork-cache.json 仅保留当前一首曲目的规范化歌名／歌手、缓存时间及匹配 URL 或失败结果：成功最多复用 1 小时，失败 5 分钟。换歌替换旧项；下一次采集检测到停止、状态不可用、元数据不全或关闭 privacy.music 时清理，不积累历史列表。私有缓存位于权限为 700 的配置目录，文件权限为 600；没有有效私有配置或目录／缓存权限不安全时使用本次临时缓存。本机缓存说明
buffered 另外在内存中为窗口近期最多 64 首曲目缓存匹配结果，成功 900 秒、失败 300 秒；补充 URL 时保留原事件观测时刻与序号。进入窗口检查点的历史歌曲 URL 随 900 秒窗口裁剪。
Worker 不再请求 Apple，也不通过 Cache API 缓存音乐匹配结果。/api/now 保留旧字段，并在上报提供时返回两个可选 URL；/api/music 始终包含这两个字段，旧 Agent 没有上报时为 null。URL 与设备快照一起受服务端 TTL 限制，本机匹配缓存不会延长在线期限。先升级 Worker，再更新 Agent。兼容升级
首页应用图标
首页优先使用仓库中的原生 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 字段。导出、署名与使用边界
保留与删除
buffered 是短期活动缓冲：本机先将应用／Music 已观测语义变化放入内存，再以权限 600 合并保存时间跨度最多 15 分钟的基线、变化和缺口；普通检查点最多每 10 秒一次，无变化覆盖心跳每 30 秒，隐私变化、启动、睡眠和上传边界立即保存。意外崩溃可能损失最近约 10 秒尚未保存的普通变化。磁盘检查点还可能落后内存约 10 秒变化／30 秒静默覆盖及阻塞延迟，文件最早数据不保证在当前时间减 15 分钟处立即物理删除。Worker 只保留最新接收的完整窗口，按 window_end + 600 秒 绝对过期。一个窗口最早的事件因此最多跨越约 25 分钟的云端有效范围。不能把它描述成“无历史”：访问者可以读取该窗口内的应用切换和曲目顺序。原始按键、鼠标点击、文档、网页历史与屏幕内容不在采集范围。
硬件每 30 秒采样，电量按整数百分比／供电变化记录，负载的小幅变化按阈值和 120 秒后的成功采样合并，不保留全部微小波动。首页普通应用／歌曲／运行列表切换按 2 秒节奏合并，不会从 API 的窗口中删除已有事件，也不是隐私过滤。页面已接收到敏感遮蔽、字段清空、音乐停止／不可用、运行列表移除、缺口、离线或新会话时立即清除旧显示；公开 API 仍可读取窗口中已上报的内容。
网页窗口只存内存，不写 localStorage；页面关闭即丢失该内存。Mac 休眠或程序停止期间不能主动执行磁盘清理，重启会校验并裁剪过期缓存，不无限补传旧活动。eco／realtime 仅保存当前 v1 快照，期限通常为 180／60 秒。v1 单曲封面缓存成功结果最多复用 1 小时，buffered 近期曲目缓存最多 900 秒；两者都不延长云端期限。
配置或屏蔽名单变更时，本机清空待发队列并开启新会话，避免下一包重发旧隐私范围内的状态；网页取得新会话后清理旧窗口。已经上传的旧窗口仍可能在新包传播前被读取；仅停止采集也要等待既有窗口到期。减少公开范围后应重新安装／启动 Agent 并检查新会话，不能将本机清理当作立即撤回所有公网副本。
TTL 不代表已抹除请求经过的所有系统日志、备份或第三方缓存，不能撤回别人已下载的数据。Cloudflare 账户级日志、观测与保留策略由部署者另行核对。遇到泄漏先停止采集并轮换 Secret，具体步骤见 安全策略。
macOS 授权
Music 自动化可能需要用户在 macOS 的系统弹窗中允许。可在“系统设置 → 隐私与安全性 → 自动化”检查运行脚本的终端或宿主是否获准控制 Music。脚本不能代替用户授予系统权限；不要通过关闭系统保护来解决。终端手动运行成功也不自动证明 launchd 执行上下文获准，应分别核验。Apple 自动化权限说明
项目不要求屏幕录制、读取浏览器历史或完整磁盘访问权限。权限被拒绝时应保持该采集项不可用，其他独立指标仍可以继续上报。