Sidra 是一款优雅的 Apple Music 桌面客户端，运行于 Linux、macOS 与 Windows。它的架构很特殊：窗口里渲染的不是自绘界面，而是music.apple.com网页本身。这就带来一个核心安全问题——如何在一个"渲染着不可信网页"的 Electron 应用里，做到登录安全、通信受控、状态不失控。本文带你拆解 Sidra 的三道防线：Apple Web 认证、IPC 通道白名单与音量回声抑制队列，看看一个"极简派"桌面客户端如何把安全做进骨头里。

为什么"套壳"客户端更需要安全设计？

普通桌面应用的窗口内容是自己写的代码，可信；而 Sidra 的窗口里跑的是 Apple Music 的网页，等于把"不可信内容"请进了主进程旁边。一旦渲染进程拿到 Node.js 能力，或主进程盲目信任网页发来的消息，风险就打开了。

Sidra 的应对思路只有三句话：渲染进程零 Node 权限、消息进出双向白名单、状态同步防反馈环。下面逐一展开。

第一道防线：Apple Web 认证——登录全程交给 Apple，凭据留在浏览器

不碰密码：认证完全走 Apple 网页流程

Sidra 自己不保存任何 Apple ID 密码。登录就是加载 Apple 的网页登录页，用户输入密码后，会话 Cookie 由 Electron 的持久分区persist:sidra接管并跨启动保存，相关代码在 src/main.ts。下次启动 Sidra 时，Apple Music 识别到 Cookie 直接续上，无需再输密码。

好处：凭据始终在浏览器会话内部，Sidra 进程层面拿不到也碰不到你的密码，卸载时删除分区目录即可彻底清除。

一个"看不见"的细节：精简登录方式

Apple 的登录框默认提供 Passkey（钥匙串）、"Sign in with iPhone" 等多种途径，这些方式依赖 Apple 生态的跨设备能力，在桌面窗口里基本走不通。Sidra 通过 src/authFrame.ts 中声明的选择器，配合注入脚本 assets/authFrameFix.js 精准隐藏这些选项，让密码登录成为可见且顺畅的那一条路——只隐藏"功能容器"，不碰其他表单元素。

伪装成普通 Chrome，而非伪装身份

Apple Music 会识别并拦截 Electron 自带的 User-Agent 指纹。Sidra 的做法是发送平台一致的 Chrome UA（macOS / Windows / Linux 各用对应平台标识，版本号直接取自已内置的 Chromium），同时剥离请求头里的 Electron 与 App 名特征（见 src/main.ts）。这不是欺骗登录，而是让一个"合法的网页环境"正常通过 Apple 的常规校验。

第二道防线：IPC 白名单——网页消息只认"花名册"

Electron 的渲染进程与主进程之间通过 IPC 通信，频道（channel）就是消息的门牌。如果网页脚本能随意往任意频道发消息，恶意页面就可能冒充 Sidra 的桥接脚本。Sidra 的答案是：双向白名单 + 编译期类型校验。

发送方向：只有花名册上的频道能过

渲染端唯一能接触到的发送入口是window.AMWrapper，它只暴露一个send函数。函数内部先查SEND_CHANNELS白名单——播放状态、当前曲目、音量变化、队列变化等 17 个合法频道全部登记在册，任何不在册的频道会被直接拦下并输出警告日志，源码见 src/preload.ts。

接收方向：命令走 postMessage 跨越隔离边界

主进程下发的播放控制（player:play、player:pause、player:setVolume等 12 个频道）由RECEIVE_CHANNELS白名单约束，经window.postMessage()送入主世界，再由钩子脚本分发到window.__sidra方法，见 src/preload.ts。

编译期兜底 + 主进程二次验票

更妙的是这套白名单由channelSet()构建，与类型声明 src/types/hook.d.ts 联动——漏登一个频道、拼错一个名字，TypeScript 编译直接报错，而不是运行期静默丢消息。主进程侧还校验消息发送方必须是主窗口的webContents且来自主框架，防止子框架或旧文档残留消息混入（src/main.ts）。

外链打开：全应用只有一个 URL 守卫

所有"在系统浏览器打开"的动作统一经过 src/utils/openExternal.ts 的openExternalUrl()：只放行http:/https:协议，解析失败或协议不符都记录日志后拒绝，且交给shell.openExternal()的是解析后的 URL而非原始字符串——因为 Chromium 会用自己的解析器重新解析参数，传原始字符串等于把校验成果交出去重算。

第三道防线：音量回声抑制队列——掐断音量"乒乓"

前两道防线管住"入口"，这道防线管住"状态同步"。Linux 上 MPRIS（系统媒体协议）与 MusicKit 双向同步音量，天然是个容易出回路的结构：

1. 你在系统音控把音量设为0.6→ MPRISset Volume写入；
2. 值经 IPC 到达 MusicKit，音量真的变了；
3. MusicKit 触发playbackVolumeDidChange→ IPC 回到 MPRIS 的updateVolume()；
4. 若此时把0.6当成"App 内音量变化"再次广播——回声产生，两边来回乒乓。

有序队列匹配回声，而不只是一个记忆槽

MPRIS 集成 的解法是一个有上限的回声队列_pendingVolumes（最多 8 个）：每次set Volume把新值压入队列；updateVolume()收到回传值时，在容差0.01内与队列比对——命中即判定为回声，丢弃该条目及更早的条目（回声按序到达，更早的值已被超越），不再广播。

几个边界都经过仔细推敲：

• 拖动场景：一次拖动会在一个回声往返内写入多个值，所以比对对象是"所有待处理值"而非只比最新值；
• 队列写满：丢弃的是新值而非最旧值——最旧值的回声还会回来，丢掉它会让回声被误判为 App 内变化，把音量拉回过时数值；而未被跟踪的新值回声只会报告播放器真实到达的音量，无害；
• 安全网：2 秒定时器兜底清空整个队列，万一某个回声永远没到，队列也会自愈，不会永久吞掉后续的真实音量变化。

小结：一张表看懂 Sidra 的安全姿态

Sidra 的安全设计没有炫技，却处处见功夫：把不可信内容关在隔离沙箱里，把每扇门的钥匙登记造册，把每个可能循环的状态配上自愈机制。对想学习 Electron 安全实践的开发者来说，这套"白名单 + 类型系统 + 防御性状态机"的组合拳，堪称一份现成的参考。更多设计细节可阅读官方规格文档 docs/SPECIFICATION.md 与项目说明 AGENTS.md。