# ALCOMD3 updater signing

言語: [English](ALCOMD3_UPDATER.md) | 日本語 | [简体中文](ALCOMD3_UPDATER.zh-CN.md)

この文書は updater key material と signature verification を扱う。完全な release
workflow は [RELEASE.ja.md](./RELEASE.ja.md) を使う。

ALCOMD3 は独自の updater key pair と `xtask` signing command を使う。ALCOMD3
release では ALCOMD3 updater key と `ALCOMD3_UPDATER_*` environment variable name を使う。

### 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 は plain Windows setup executable `alcomd3-{version}-setup.exe` を検証する。
- `.zip` artifact は browser download compatibility 用であり、updater には使わない。

Updater JSON には artifact URL と literal signature content を入れる。signature file URL は使わない。

### Key pair 生成

Key pair は bootstrap または意図的な updater key rotation の場合のみ生成する:

```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`: signing 用の portable environment file。
- `private-key.ps1`: signing 用の PowerShell environment file。

Private key file は ignore され、commit してはならない。安全な場所に backup する。Private key を失うと、埋め込み public key を使う build は将来 version に auto-update できない。

### Signing variable の読み込み

`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
```

Portable `.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` file を読み、内容を `signature` field に入れる。

### Updater JSON 検証

Website 公開前に最終 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 release では代わりに `tauri-updater-beta.json` を検証する。

検証では、JSON parse、`platforms.windows-x86_64` の存在、signature の存在、URL と installer file name の一致、`vrc-get-gui/src/updater.rs` の public key による signature verification を確認する。

### Key rotation rule

通常 release 内で updater key を rotate しない。避けられない場合は、old key で署名され new embedded public key を含む bridge release を先に公開し、その後の installer を new private key で署名する。
