# ALCOMD3 updater signing

语言: [English](ALCOMD3_UPDATER.md) | [日本語](ALCOMD3_UPDATER.ja.md) | 简体中文

本文档只覆盖 updater key material 和签名验证。完整发布流程使用 [RELEASE.zh-CN.md](./RELEASE.zh-CN.md)。

ALCOMD3 使用自己的 updater key pair 和 `xtask` 签名命令。ALCOMD3 发布使用 ALCOMD3 updater key 和 `ALCOMD3_UPDATER_*` 环境变量名。

### Key model

- updater public key 嵌入在 `vrc-get-gui/src/updater.rs` 的 `static PUBLIC_KEY`。
- private key 由 `xtask sign-alcom-updater` 从以下变量读取：
  - `ALCOMD3_UPDATER_PRIVATE_KEY`
  - `ALCOMD3_UPDATER_PRIVATE_KEY_PASSWORD`
- updater 验证普通 Windows setup executable：`alcomd3-{version}-setup.exe`。
- `.zip` artifact 只用于浏览器下载兼容，不被 updater 使用。

Updater JSON 必须包含 artifact URL 和签名文件的实际内容，而不是签名文件 URL。

### 生成 key pair

仅在初始化或有意轮换 updater key 时生成 key pair：

```powershell
$bytes = [byte[]]::new(32)
$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rng.GetBytes($bytes)
$rng.Dispose()
$env:ALCOMD3_UPDATER_PRIVATE_KEY_PASSWORD = [Convert]::ToBase64String($bytes)
cargo xtask generate-alcom-updater-key
```

生成文件位于 `artifacts/alcomd3-updater-key/`：

- `public-key-base64.txt`：复制到 `vrc-get-gui/src/updater.rs`。
- `private-key.env`：可移植签名环境文件。
- `private-key.ps1`：PowerShell 签名环境文件。

Private key 文件已 ignore，不能提交。请安全备份。如果 private key 丢失，使用已嵌入 public key 的 build 将无法自动更新到未来版本。

### 加载签名变量

`cargo xtask release-build` 会在 signing variable 未设置时自动加载
`artifacts/alcomd3-updater-key/`，优先使用 `private-key.ps1`，否则使用
`private-key.env`。

PowerShell：

```powershell
. .\artifacts\alcomd3-updater-key\private-key.ps1
```

可移植 `.env` loader：

```powershell
Get-Content .\artifacts\alcomd3-updater-key\private-key.env | ForEach-Object {
    $name, $value = $_ -split '=', 2
    [Environment]::SetEnvironmentVariable($name, $value, 'Process')
}
```

### 签名 installer

```powershell
$Version = "2.0.0"
$SetupDir = "target\x86_64-pc-windows-msvc\release\bundle\setup"
$Installer = "$SetupDir\alcomd3-$Version-setup.exe"
cargo xtask sign-alcom-updater $Installer
```

输出：

```text
target/x86_64-pc-windows-msvc/release/bundle/setup/alcomd3-{version}-setup.exe.sig
```

Updater JSON generator 会读取 `.sig` 文件，并将内容写入 `signature` field。

### 验证 updater JSON

发布网站前必须验证最终 updater JSON：

```powershell
$Version = "2.0.0"
$SetupDir = "target\x86_64-pc-windows-msvc\release\bundle\setup"
cargo xtask verify-alcom-updater-json `
    --installer "$SetupDir\alcomd3-$Version-setup.exe" `
    --json website\public\api\gui\tauri-updater.json
```

Beta 发布改为验证 `tauri-updater-beta.json`。

验证会检查 JSON 可解析、`platforms.windows-x86_64` 存在、signature 存在、URL 与 installer 文件名匹配，并用 `vrc-get-gui/src/updater.rs` 中的 public key 验证签名。

### Key rotation rule

不要在普通发布中轮换 updater key。若无法避免，必须先发布一个由旧 key 签名且包含新 embedded public key 的 bridge release，之后的 installer 才能用新 private key 签名。
