umbrix/update-server/CODE_SIGNING_WINDOWS.md

# Подпись кода для Windows (Code Signing)

## Зачем нужен сертификат?

При установке `.exe` файла без цифровой подписи Windows показывает предупреждения:
- ⚠️ "Неизвестный издатель"
- ⚠️ "Windows защитила ваш компьютер"
- ⚠️ Windows Defender может блокировать файл

**С сертификатом:**
- ✅ "Проверенный издатель: Umbrix Team"
- ✅ Нет предупреждений SmartScreen
- ✅ Пользователи доверяют приложению

## Текущее состояние (БЕЗ сертификата)

Приложение **РАБОТАЕТ**, но:
1. При установке Windows показывает "Неизвестный издатель"
2. Пользователь должен нажать "Все равно запустить"
3. Антивирус может блокировать (ложное срабатывание)

**Для внутреннего использования это НОРМАЛЬНО** ✅

## Где получить сертификат?

### 1. Коммерческие сертификаты (EV Code Signing)

**Recommended:** Extended Validation (EV) - сразу доверие Windows

| Провайдер | Цена/год | Особенности |
|-----------|----------|-------------|
| **DigiCert** | $469-799 | Лучшая репутация, EV на USB токене |
| **Sectigo (Comodo)** | $399-599 | Популярный, хорошая поддержка |
| **GlobalSign** | $349-599 | Быстрое получение (1-2 дня) |
| **SSL.com** | $299-499 | Дешевле, но дольше проверка |
| **Certum** | €199-399 | Европейский, принимают криптовалюту |

**EV сертификат (Extended Validation):**
- ✅ Сразу доверие Windows SmartScreen
- ✅ Зелёная подпись "Проверенный издатель"
- ✅ Никаких предупреждений
- 📦 Выдается на USB токене (нельзя скопировать)
- ⏱️ Проверка документов 3-7 дней

**Обычный Code Signing (не EV):**
- ⚠️ Доверие нарастает со временем (нужно минимум 100-1000 установок)
- ⚠️ Первые месяцы будут предупреждения SmartScreen
- 💾 Файл .pfx/.p12 (можно хранить локально)
- ⏱️ Получение 1-2 дня

### 2. Требования для получения

**Документы:**
- Регистрация компании (ИНН, ОГРН, выписка из ЕГРЮЛ)
- ИЛИ ИП (ОГРНИП)
- ИЛИ личность физлица (паспорт, утилиты)

**Проверка:**
- Подтверждение номера телефона
- Email компании (домен должен совпадать)
- Банковские реквизиты
- Адрес офиса (могут позвонить или прислать письмо с кодом)

### 3. Процесс получения (DigiCert EV пример)

```
1. Заказ → 2-3 минуты (онлайн форма)
   ↓
2. Оплата → $799/год
   ↓
3. Проверка документов → 3-7 дней
   - Загрузка ЕГРЮЛ/паспорта
   - Подтверждение телефона
   - Проверка адреса
   ↓
4. Отправка USB токена → 1-5 дней (DHL/FedEx)
   ↓
5. Установка драйверов → 10 минут
   ↓
6. Готово! Можно подписывать код
```

## Как подписать файл после получения сертификата

### С EV сертификатом (USB токен)

```powershell
# 1. Установить Windows SDK (включает signtool.exe)
# Скачать: https://developer.microsoft.com/windows/downloads/windows-sdk/

# 2. Подключить USB токен

# 3. Подписать EXE
$signtool = "C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x64\signtool.exe"
& $signtool sign /tr http://timestamp.digicert.com /td sha256 /fd sha256 /a "umbrix-1.7.3-windows-setup.exe"

# Результат:
# Successfully signed: umbrix-1.7.3-windows-setup.exe
```

### С обычным Code Signing (.pfx файл)

```powershell
# 1. Экспортировать сертификат в .pfx с паролем

# 2. Подписать EXE
$signtool = "C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x64\signtool.exe"
& $signtool sign /f "umbrix-cert.pfx" /p "PASSWORD" /tr http://timestamp.digicert.com /td sha256 /fd sha256 "umbrix-1.7.3-windows-setup.exe"
```

### Проверка подписи

```powershell
# Посмотреть информацию о подписи
$signtool verify /pa /v "umbrix-1.7.3-windows-setup.exe"

# Или через GUI: ПКМ → Свойства → Цифровые подписи
```

## Автоматизация с GitHub Actions

```yaml
name: Build & Sign Windows

on:
  push:
    tags: ['v*']

jobs:
  build-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.24.0'
      
      - name: Build Windows
        run: flutter build windows --release
      
      - name: Build Installer
        run: iscc windows/installer.iss
      
      # Для EV сертификата - использовать self-hosted runner с USB токеном
      # Для обычного - загрузить .pfx в GitHub Secrets
      
      - name: Sign EXE
        env:
          CERT_PASSWORD: ${{ secrets.CERT_PASSWORD }}
        run: |
          # Импорт .pfx из секрета
          $cert = [Convert]::FromBase64String("${{ secrets.CERT_BASE64 }}")
          [IO.File]::WriteAllBytes("cert.pfx", $cert)
          
          # Подпись
          $signtool = "C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x64\signtool.exe"
          & $signtool sign /f cert.pfx /p $env:CERT_PASSWORD /tr http://timestamp.digicert.com /td sha256 /fd sha256 dist/umbrix-1.7.3-windows-setup.exe
          
          # Удалить временный .pfx
          Remove-Item cert.pfx
      
      - name: Upload to Gitea
        run: |
          curl -X POST "https://update.umbrix.net/api/v1/repos/vodorod/umbrix/releases/assets" `
            -H "Authorization: token ${{ secrets.GITEA_TOKEN }}" `
            --data-binary "@dist/umbrix-1.7.3-windows-setup.exe"
```

## Альтернативы (НЕ рекомендуется)

### 1. Self-Signed сертификат (для тестирования)

```powershell
# Создать self-signed сертификат
$cert = New-SelfSignedCertificate -Type CodeSigningCert -Subject "CN=Umbrix Team" -CertStoreLocation Cert:\CurrentUser\My

# Экспортировать
$pwd = ConvertTo-SecureString -String "password123" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath umbrix-selfsigned.pfx -Password $pwd

# Подписать
signtool sign /f umbrix-selfsigned.pfx /p password123 /fd sha256 umbrix-1.7.3.exe
```

**⚠️ Проблемы:**
- Windows все равно показывает предупреждение
- Нужно вручную добавлять сертификат в доверенные
- НЕ работает на других компьютерах
- Только для внутреннего тестирования

### 2. Open Source Certificate (StartSSL, Let's Encrypt)

❌ **Не работает для Code Signing!**
- Let's Encrypt выдает только SSL/TLS (для HTTPS)
- Code Signing требует проверку юрлица
- Нет бесплатных Code Signing сертификатов

### 3. Использование osslsigncode (Linux подпись Windows файлов)

```bash
# Установка на Linux
sudo apt install osslsigncode

# Подпись (с .pfx сертификатом)
osslsigncode sign \
  -pkcs12 umbrix-cert.pfx \
  -pass "PASSWORD" \
  -ts http://timestamp.digicert.com \
  -in umbrix-1.7.3-windows-setup.exe \
  -out umbrix-1.7.3-windows-setup-signed.exe
```

## Рекомендации для Umbrix

### Для разработки и тестирования (СЕЙЧАС):
✅ **Без сертификата** - просто предупреждение Windows
- Пользователи могут нажать "Все равно запустить"
- Работает для внутреннего использования
- Бесплатно

### Для публичного релиза (БУДУЩЕЕ):
✅ **DigiCert EV Code Signing** ($799/год)
- Сразу доверие Windows
- Нет предупреждений
- Профессиональный вид
- Рекомендуется для коммерческого продукта

### Для малого бюджета:
✅ **Certum Open Source Code Signing** (€199/год)
- Дешевле других
- Принимают криптовалюту
- Специальная цена для Open Source проектов
- Требуют ссылку на GitHub/GitLab

## Ссылки

**Покупка сертификатов:**
- DigiCert: https://www.digicert.com/signing/code-signing-certificates
- Sectigo: https://sectigo.com/ssl-certificates-tls/code-signing
- GlobalSign: https://www.globalsign.com/en/code-signing-certificate
- SSL.com: https://www.ssl.com/certificates/code-signing/
- Certum: https://en.sklep.certum.pl/data-safety/code-signing-certificates/

**Документация:**
- Microsoft Code Signing: https://learn.microsoft.com/windows/win32/seccrypto/cryptography-tools
- signtool.exe: https://learn.microsoft.com/windows-hardware/drivers/devtest/signtool

**Проверка репутации SmartScreen:**
- https://www.microsoft.com/en-us/wdsi/filesubmission

## FAQ

**Q: Можно ли работать без сертификата?**  
A: Да! Приложение будет работать, но Windows покажет предупреждение "Неизвестный издатель". Для личного/внутреннего использования это OK.

**Q: Как быстро получить доверие SmartScreen с обычным сертификатом?**  
A: Нужно минимум 100-1000 установок за 2-3 месяца. EV сертификат дает доверие сразу.

**Q: Можно ли использовать сертификат на Linux для подписи Windows файлов?**  
A: Да, через `osslsigncode`. Но EV сертификаты на USB токене работают только на Windows.

**Q: Что дешевле - EV или обычный Code Signing?**  
A: Обычный дешевле ($299 vs $799), но нужно ждать наработки репутации. EV дороже, но доверие сразу.

**Q: Сертификат для Umbrix - обязателен?**  
A: Для закрытого тестирования - НЕТ. Для публичного релиза - ОЧЕНЬ ЖЕЛАТЕЛЬНО.

## Итого

**Текущая конфигурация обновлений:**
- ✅ Файл: `.exe` установщик (Inno Setup)
- ✅ Приоритет поиска: x64 → amd64 → win64 → setup → installer → любой .exe
- ✅ Установка: PowerShell с `/VERYSILENT /SUPPRESSMSGBOXES /NORESTART`
- ✅ Автоперезагрузка: через 2 секунды
- ⚠️ Сертификат: НЕТ (показывает предупреждение, но работает)

**Следующие шаги:**
1. Собрать Windows версию на машине с Windows
2. Создать Inno Setup установщик
3. Загрузить в Gitea релиз
4. Протестировать автообновление
5. (Опционально) Купить сертификат для публичного релиза