75 lines
4.6 KiB
Markdown
75 lines
4.6 KiB
Markdown
# Skill: Windows Services / PowerShell / Elevation
|
||
|
||
## Когда использовать
|
||
|
||
Используй этот skill при изменениях ProxiFyre/sing-box install/start/stop/update/uninstall, UAC/admin boundary, native inventory, NSIS upgrade/uninstall или build/release/QA PowerShell scripts.
|
||
|
||
## Цель
|
||
|
||
Сохранять системные операции явными, native и проверяемыми. Production runtime не зависит от PowerShell; Rust владеет Windows SCM, registry, process, filesystem, package verification и UAC flow.
|
||
|
||
## Runtime-инварианты
|
||
|
||
- Install/start/stop/update/uninstall/migrate — только явные действия пользователя.
|
||
- `apply` не устанавливает, не обновляет, не переносит и не удаляет компоненты.
|
||
- Current managed roots — только `C:\Program Files\ProxyWarden\components\ProxiFyre` и `...\sing-box`.
|
||
- Service control требует exact `PathName`, marker/receipt, canonical path и non-reparse checks. Имя службы или fuzzy candidate недостаточны.
|
||
- Elevated UI action передаёт только UUID sealed job record; fixed early mode сам повторно проверяет ACL, TTL, action, paths, hashes и ownership.
|
||
- NSIS использует только exact `--nsis-verify-upgrade` и `--nsis-uninstall-managed`; никаких user/path/script arguments.
|
||
- Active/recovery/pending cutover journal блокирует upgrade/uninstall и не удаляется общим cleanup.
|
||
- Runtime-generated scripts и запуск `powershell.exe`/`pwsh` запрещены.
|
||
|
||
## PowerShell allowlist
|
||
|
||
PowerShell остаётся только для build/release/QA:
|
||
|
||
- `scripts/check-runtime-powershell-boundary.ps1`;
|
||
- `scripts/update-component-bundle.ps1`;
|
||
- `scripts/prepare-release.ps1`;
|
||
- `scripts/audit-windows-smoke.ps1`.
|
||
|
||
`PlanOnly`/`CheckOnly` должны быть side-effect-free и возвращать structured JSON с `changed: false`. Любой новый `.ps1`, `.psm1`, `.psd1`, production caller или bundled cleanup resource должен ломать boundary checker.
|
||
|
||
## Native service flow
|
||
|
||
1. Получить inventory через Windows API и canonicalize все пути.
|
||
2. Классифицировать `Missing / Managed / Foreign / Incomplete` до первой mutation.
|
||
3. Проверить marker/receipt, service `PathName`, file identity, ACL и reparse boundary.
|
||
4. Захватить общий lifecycle lock.
|
||
5. Выполнить только allowlisted fixed action.
|
||
6. Query-back подтвердить service/path/start policy/state.
|
||
7. При ошибке оставить durable recovery state; не угадывать cleanup.
|
||
|
||
Для uninstall сначала preflight всех компонентов. `Missing` — no-op; `Foreign`/`Incomplete` — zero mutation. Running service сначала останавливается и проверяется, затем удаляется. MSI code `3010` означает success with reboot required, а не обычную ошибку.
|
||
|
||
## Удаление файлов
|
||
|
||
- Не использовать generic recursive delete по app root.
|
||
- Удалять только exact receipt/journal-owned entries после safe-path, ACL, reparse и file-shape checks.
|
||
- `.proxywarden-cutover` и `.proxywarden-quarantine` удаляет только owner terminal retirement после проверки journal state.
|
||
- Unexpected files, active jobs, process/service references или partial tombstone блокируют cleanup.
|
||
|
||
## Проверка
|
||
|
||
Cross-platform/pure logic:
|
||
|
||
```powershell
|
||
Push-Location src-tauri
|
||
cargo fmt --all -- --check
|
||
cargo clippy --all-targets --all-features -- -D warnings
|
||
cargo test --all-targets
|
||
Pop-Location
|
||
|
||
& .\scripts\check-runtime-powershell-boundary.ps1 -CheckOnly
|
||
& .\scripts\update-component-bundle.ps1 -CheckOnly
|
||
& .\scripts\audit-windows-smoke.ps1 -Mode PlanOnly
|
||
```
|
||
|
||
Реальная проверка требует Windows 10/11 x64 VM: UAC cancel/success, SCM create/start/stop/delete, driver/VC installer exit codes, fresh offline install, foreign same-name service refusal, legacy rollback/recovery и NSIS upgrade/uninstall/reboot.
|
||
|
||
Не называть service/elevation behavior проверенным без этой VM evidence.
|
||
|
||
## Как отчитываться
|
||
|
||
Перед финальным ответом применить `.agent/skills/communication-reporting/SKILL.md` и `.agent/checklists/communication.md`. Отдельно перечислить automated evidence, Windows/manual evidence и незакрытые UAC/SCM/driver риски.
|