fix: закрыть каналы утечки секретов и сделать PHASE 1 владением оркестратора

Hardening-проход перед первой сборкой на Debian. Три из найденного не
воспроизводились ни на одном dry-run и проявились бы только на живом сервере.

Установка

* preflight внутри install вызывался дважды и оба раза проверял clean-host.
  Ко второму вызову на диске лежал собственный /var/lib/hy2xs/install-state.json,
  записанный после первого preflight, и опознавался как маркер посторонней
  установки: КАЖДАЯ чистая установка падала сразу после apt-get с
  fatal_post_apply и оставляла сервер наполовину настроенным. Чистота хоста —
  условие входа в операцию, возможности платформы проверяются уже внутри
  PHASE 1, поэтому checkCleanHost стал отдельным параметром без умолчания.

* PHASE 1 начиналась в install.sh: shell сам создавал /usr/local/lib/hy2xs,
  ставил бинарник, вешал symlink и копировал runtime-пакет, и только потом
  запускал оркестратор с его собственным preflight. Отказ того preflight
  объявлялся fatal_pre_apply — «на сервере ничего не изменено» — при уже
  созданном каталоге оркестратора. Отследить владение мутацией невозможно,
  пока мутируют двое: install.sh больше не изменяет ничего, раскладку
  выполняет steps/bootstrap.ts под ownership.bootstrapTouched, пути попали
  в owned_paths. Как следствие удалено деление clean-host на фазы.

* diagnosticsCollect стояла перед rollback обычным await в install и в
  reconfigure. На заполненном диске она падает сама и отменяла откат целиком.
  Диагностика — best effort, откат — обязателен.

* reconfigure/repair выбирали записываемую фазу отказа регулярным выражением
  по тексту ошибки. Переведено на ownership-флаги.

Секреты

* Журнал админки писал RequestURI, то есть путь вместе с query. Hysteria
  обращается к /internal/hysteria/auth?access_token=<секрет> при каждом
  подключении пира, поэтому действующий machine token оседал открытым текстом
  в hy2xs-admin.log, который отдаётся через ExportLog и попадает в
  diagnostics-бандл. Логируется путь; значения query не пишутся, имена —
  пишутся. Канала было два: gin.Default() печатает path?query в stdout,
  оттуда в journald и в тот же бандл, — панель переведена на gin.New() +
  Recovery(). Журналы внутри бандла и журнал Hysteria из ExportLog теперь
  проходят санитайз. Сравнение токена — constant time.

* Config API позволял прочитать и подменить ключи приложения: getConfig и
  listConfig принимали произвольный ключ, а проверка записи была denylist'ом
  из трёх ключей оркестратора. Запрос ?key=PEER_SECRET_ENCRYPTION_KEY отдавал
  master-key шифрования секретов пиров. Доступ переведён на allowlist, маршрут
  getConfig удалён целиком — потребителей у него не было ни одного.

Пиры

* Импорт применялся по одной записи вне транзакции, вопреки собственному
  контракту. Валидация не знает, что уже лежит в базе: cross-conflict по
  UNIQUE(name) оставлял часть файла применённой. Применение выполняется одной
  транзакцией, криптоматериал считается до её открытия.

* Файл импорта мог содержать хвостовой JSON-документ, который молча не
  применялся. После разбора проверяется io.EOF.

* Экспорт разделён на «Экспорт настроек» и «Резервная копия» с секретами и
  подтверждением: обычный экспорт выдаёт пирам новые секреты при импорте, и
  прежние клиентские ссылки после переноса переставали работать.

Сборка

* Два stale-грепа в приёмке роняли build.sh в самом конце, внутри
  verify_archive. Первый искал в smoke.ts исчезнувший литерал URL, второй
  совпадал с router_test.go, который перечисляет удалённые маршруты, потому
  что проверяет их отсутствие: добавление регрессионного теста ломало сборку.

* verify_archive требовал наличия мутирующей строки в install.sh. Инвариант
  перевёрнут: их не должно быть ни одной.

Очистка

* Удалены entity.LegacyAccount, миграции 002/003 и мёртвые хелперы
  listSQLMigrationFiles и envInt: v1 не мигрирует базу 0.x ни при каком
  сценарии. Номера оставшихся миграций сохранены. H UI-словарь убран из
  обычных доков, в docs/14 он остаётся — там это имена объектов для удаления.

* Список непубличных IPv4 приведён к IANA Special-Purpose Address Registry:
  203.0.113.5 из RFC-примеров считался публичным адресом сервера. Отказ
  резолвера отделён от отсутствия A-записи.

Проверено: bun test 233, go test 71, tsc/vue-tsc, bash -n 11 скриптов,
приёмка прогнана против дерева.

orchestrator/src/commands/diagnostics.ts

@@ -1,7 +1,7 @@
 import type { CommonOptions } from "../types/context";
 import { info, setOperationContext } from "../lib/log";
 import { runMutating } from "../lib/process";
-import { redactEnv, redactYaml } from "../lib/redaction";
+import { redactEnv, redactLogText, redactYaml } from "../lib/redaction";
 
 function shellEscapeSingleQuotes(value: string): string {
   return value.replaceAll("'", "'\\''");
@@ -49,6 +49,24 @@ export async function diagnosticsCollect(_options: CommonOptions): Promise<void>
     // noop
   }
 
+  // Журналы и вывод systemctl — такой же артефакт, покидающий сервер, как env
+  // и YAML. Раньше редактировались только последние два, а journal-admin.log
+  // копировался как есть — и уносил machine token, который админка логировала
+  // в составе RequestURI.
+  for (const logFile of [
+    "journal-hysteria.log",
+    "journal-admin.log",
+    "systemd-hysteria.txt",
+    "systemd-admin.txt"
+  ]) {
+    try {
+      const raw = await Bun.file(`${outDir}/${logFile}`).text();
+      await Bun.write(`${outDir}/${logFile}`, redactLogText(raw));
+    } catch {
+      // noop
+    }
+  }
+
   await runMutating`sh -c ${`tar -czf '${shellEscapeSingleQuotes(archive)}' -C '${shellEscapeSingleQuotes(outDir)}' .`}`;
 
   info(`diagnostics bundle collected: ${archive}`);

orchestrator/src/commands/install.ts

@@ -9,7 +9,14 @@ import {
   buildInstallStateRecord
 } from "../lib/installState";
 import { parseRuntimeEnv, renderRuntimeEnv } from "../config/env";
+import {
+  ORCHESTRATOR_INSTALL_DIR,
+  ORCHESTRATOR_INSTALL_PATH,
+  ORCHESTRATOR_SYMLINK_PATH,
+  RUNTIME_PACKAGE_DIR
+} from "../config/profile";
 import { preflight } from "../steps/preflight";
+import { bootstrapRuntime } from "../steps/bootstrap";
 import { installDeps } from "../steps/deps";
 import { prepareFilesystem } from "../steps/filesystem";
 import { deployUi } from "../steps/ui";
@@ -24,6 +31,7 @@ import { diagnosticsCollect } from "./diagnostics";
 type InstallPhase =
   | "installing"
   | "preflight_ok"
+  | "bootstrap_installed"
   | "deps_ok"
   | "filesystem_ready"
   | "runtime_env_written"
@@ -56,6 +64,12 @@ type InstallPhase =
 type OperationOwnership = {
   /** install-state.json уже создан: сам по себе делает хост изменённым. */
   stateWritten: boolean;
+  /**
+   * Раскладка самого оркестратора и runtime-пакета (/usr/local/lib/hy2xs,
+   * symlink в /usr/local/bin). Раньше эти пути создавал install.sh, и они
+   * оставались вне учёта владения целиком.
+   */
+  bootstrapTouched: boolean;
   depsTouched: boolean;
   filesystemTouched: boolean;
   uiTouched: boolean;
@@ -79,6 +93,7 @@ type FailureKind =
 function newOwnership(): OperationOwnership {
   return {
     stateWritten: false,
+    bootstrapTouched: false,
     depsTouched: false,
     filesystemTouched: false,
     uiTouched: false,
@@ -102,7 +117,14 @@ function installOwnedPaths(context: InstallContext): string[] {
     "/etc/systemd/system/hysteria-server.service",
     "/etc/nftables.conf",
     "/etc/nftables.d/hy2xs.nft",
-    context.config.installDir
+    context.config.installDir,
+    // Bootstrap-пути принадлежат установке так же, как всё остальное. Пока их
+    // раскладывал install.sh, они не попадали ни в owned_paths, ни в rollback,
+    // и purge приходилось держать шире, чем маркер установки.
+    ORCHESTRATOR_INSTALL_DIR,
+    ORCHESTRATOR_INSTALL_PATH,
+    ORCHESTRATOR_SYMLINK_PATH,
+    RUNTIME_PACKAGE_DIR
   ];
 }
 
@@ -167,6 +189,7 @@ export function classifyFailure(ownership: OperationOwnership, phase: InstallPha
     ownership.uiTouched ||
     ownership.filesystemTouched ||
     ownership.depsTouched ||
+    ownership.bootstrapTouched ||
     ownership.stateWritten
   ) {
     return "fatal_post_apply";
@@ -189,6 +212,11 @@ async function rollbackFailedInstall(
     return;
   }
 
+  // Bootstrap-пути (/usr/local/lib/hy2xs, symlink, runtime-пакет) намеренно не
+  // удаляются: именно ими и работает `repair --allow-partial-state`, ради
+  // которого install-state сохраняется с repair_hint. Снести оркестратор при
+  // откате означало бы лишить оператора инструмента починки. Полная зачистка —
+  // это осознанное отдельное действие, tools/legacy/purge-v0.sh.
   if (ownership.firewallTouched) {
     await rollbackFirewallNow(context);
   }
@@ -237,18 +265,28 @@ export async function install(options: InstallOptions): Promise<void> {
   try {
     // PHASE 1 начинается только после успешного preflight: до него install
     // не пишет ни одного persistent path, включая install-state.
+    //
+    // Контракт чистого хоста проверяется здесь — последний раз за операцию.
+    // Всё, что дальше, уже создаёт наши собственные пути, и повторная проверка
+    // опознала бы их как чужую установку.
     step("preflight");
-    await preflight(context, { requireCapabilities: false, cleanHostPhase: "install" });
+    await preflight(context, { requireCapabilities: false, checkCleanHost: true });
     stepDone("preflight");
 
     await advanceInstallState(context, ownership, "preflight_ok");
     phase = "preflight_ok";
+    step("orchestrator bootstrap");
+    ownership.bootstrapTouched = true;
+    context.options.packageDir = await bootstrapRuntime(context);
+    stepDone("orchestrator bootstrap");
+    await advanceInstallState(context, ownership, "bootstrap_installed");
+    phase = "bootstrap_installed";
     step("system dependencies");
     ownership.depsTouched = true;
     await installDeps(context);
     stepDone("system dependencies");
     step("preflight capabilities");
-    await preflight(context, { requireCapabilities: true, cleanHostPhase: "install" });
+    await preflight(context, { requireCapabilities: true, checkCleanHost: false });
     stepDone("preflight capabilities");
     await advanceInstallState(context, ownership, "deps_ok");
     phase = "deps_ok";
@@ -341,7 +379,22 @@ export async function install(options: InstallOptions): Promise<void> {
       failureKind === "smoke_readiness_timeout" ? "smoke_failed" : "failed",
       `${failureKind}: ${message}`
     );
-    await diagnosticsCollect(options);
+
+    // Диагностика — best effort, откат — обязателен.
+    //
+    // diagnosticsCollect создаёт каталог, копирует файлы и упаковывает tar:
+    // при заполненном диске, битой ФС или недоступном journalctl она падает
+    // сама. Пока она стояла перед откатом обычным await, её собственный отказ
+    // отменял откат целиком — то есть худший сценарий отказа установки
+    // гарантированно лишался единственного механизма восстановления.
+    try {
+      await diagnosticsCollect(options);
+    } catch (diagnosticsError) {
+      const diagnosticsMessage =
+        diagnosticsError instanceof Error ? diagnosticsError.message : String(diagnosticsError);
+      info(`diagnostics collection failed, continuing with rollback: ${diagnosticsMessage}`);
+    }
+
     await rollbackFailedInstall(context, ownership, failureKind);
     throw error;
   }

orchestrator/src/commands/preflight-install.ts

@@ -36,7 +36,7 @@ export async function preflightInstall(options: InstallOptions): Promise<void> {
   };
 
   step("bootstrap preflight (read-only)");
-  await preflight(context, { requireCapabilities: false, cleanHostPhase: "bootstrap" });
+  await preflight(context, { requireCapabilities: false, checkCleanHost: true });
   stepDone("bootstrap preflight (read-only)");
 
   info("clean-host contract satisfied: no persistent path was modified");

orchestrator/src/commands/reconfigure.ts

@@ -27,10 +27,53 @@ type ReconfigurePhase =
   | "firewall_applied"
   | "runtime_env_written"
   | "smoke_ok"
+  | "reconfigure_failed"
   | "firewall_connectivity_failure"
   | "smoke_failed"
   | "installed";
 
+/**
+ * К чему текущий проход reconfigure/repair уже мог прикоснуться.
+ *
+ * Та же формулировка и та же причина, что и в install: флаг взводится ПЕРЕД
+ * шагом, потому что шаг умеет изменить систему и упасть.
+ *
+ * Раньше записанная фаза отказа выбиралась регулярным выражением по тексту
+ * ошибки (`/firewall|nft|ssh port check failed/i`). Это ровно тот приём,
+ * который убрали из install: сообщение о недоступном DNS, в котором случайно
+ * встретилось слово nft, объявляло бы отказ проблемой firewall, а падение
+ * `nft -c` на этапе smoke — наоборот, отказом smoke. install-state — то, что
+ * оператор читает первым; в нём должно стоять, где на самом деле остановились.
+ */
+type ReconfigureOwnership = {
+  configTouched: boolean;
+  unitsTouched: boolean;
+  firewallTouched: boolean;
+  envTouched: boolean;
+  servicesRestarted: boolean;
+};
+
+function newReconfigureOwnership(): ReconfigureOwnership {
+  return {
+    configTouched: false,
+    unitsTouched: false,
+    firewallTouched: false,
+    envTouched: false,
+    servicesRestarted: false
+  };
+}
+
+/** Порядок веток — от самой поздней стадии к самой ранней. */
+export function classifyReconfigureFailure(ownership: ReconfigureOwnership): ReconfigurePhase {
+  if (ownership.servicesRestarted) {
+    return "smoke_failed";
+  }
+  if (ownership.firewallTouched) {
+    return "firewall_connectivity_failure";
+  }
+  return "reconfigure_failed";
+}
+
 function operationKey(context: ReconfigureContext): string {
   return context.installDate;
 }
@@ -194,21 +237,27 @@ export async function reconfigure(options: ReconfigureOptions): Promise<void> {
   await backupCurrentState();
   stepDone("backup");
 
+  const ownership = newReconfigureOwnership();
+
   try {
     await markPhase(context, options.allowPartialState ? "repairing" : "reconfiguring");
     step("config generation");
+    ownership.configTouched = true;
     await generateConfig(context);
     stepDone("config generation");
     await markPhase(context, "config_generated");
     step("systemd units");
+    ownership.unitsTouched = true;
     await deploySystemd(context);
     stepDone("systemd units");
     await markPhase(context, "units_deployed");
     step("firewall");
+    ownership.firewallTouched = true;
     await applyFirewall(context);
     stepDone("firewall");
     await markPhase(context, "firewall_applied");
     step("write env artifacts");
+    ownership.envTouched = true;
     await writeTextAtomic(options.runtimeConfigPath, renderRuntimeEnv(config), {
       mode: 0o600,
       owner: "root",
@@ -219,6 +268,7 @@ export async function reconfigure(options: ReconfigureOptions): Promise<void> {
     stepDone("write env artifacts");
     await markPhase(context, "runtime_env_written");
     step("smoke checks");
+    ownership.servicesRestarted = true;
     await smoke(context);
     stepDone("smoke checks");
     await markPhase(context, "smoke_ok");
@@ -234,12 +284,26 @@ export async function reconfigure(options: ReconfigureOptions): Promise<void> {
   } catch (error) {
     info("reconfigure failed, rollback in progress");
     const message = error instanceof Error ? error.message : String(error);
-    const phase: ReconfigurePhase = /firewall|nft|ssh port check failed/i.test(message)
-      ? "firewall_connectivity_failure"
-      : "smoke_failed";
-    await markPhase(context, phase, message);
-    await diagnosticsCollect(options);
-    await rollbackFirewallNow(context);
+    await markPhase(context, classifyReconfigureFailure(ownership), message);
+
+    // Диагностика — best effort, откат — обязателен.
+    //
+    // diagnosticsCollect создаёт каталог, копирует файлы и упаковывает tar:
+    // на заполненном диске она падает сама. Пока она стояла перед откатом
+    // обычным await, её отказ отменял и rollbackFirewallNow, и восстановление
+    // конфигов из /etc/hy2xs/backups — то есть сервер оставался с применённым
+    // сломанным firewall и без единственного механизма возврата.
+    try {
+      await diagnosticsCollect(options);
+    } catch (diagnosticsError) {
+      const diagnosticsMessage =
+        diagnosticsError instanceof Error ? diagnosticsError.message : String(diagnosticsError);
+      info(`diagnostics collection failed, continuing with rollback: ${diagnosticsMessage}`);
+    }
+
+    if (ownership.firewallTouched) {
+      await rollbackFirewallNow(context);
+    }
     await rollbackCurrentState();
     throw error;
   }

orchestrator/src/config/profile.ts

@@ -41,6 +41,36 @@ export const HY2XS_TARGET_ARCH = "amd64";
 export const ADMIN_API_BASE = "/api";
 export const HYSTERIA_MACHINE_AUTH_PATH = "/internal/hysteria/auth";
 
+/**
+ * Где оркестратор живёт на установленном хосте.
+ *
+ * Эти пути раскладывает шаг `bootstrapRuntime` в самом начале PHASE 1, и они же
+ * являются clean-host маркерами чужой установки. Объявлены здесь один раз
+ * именно потому, что у них два потребителя с противоположными ролями:
+ * steps/bootstrap.ts их создаёт, steps/cleanHost.ts на них отказывает.
+ * Разошедшиеся копии означали бы, что установка создаёт путь, который её
+ * собственный контракт чистоты не проверяет.
+ */
+export const ORCHESTRATOR_INSTALL_DIR = "/usr/local/lib/hy2xs";
+export const ORCHESTRATOR_INSTALL_PATH = `${ORCHESTRATOR_INSTALL_DIR}/hy2xs-orchestrator`;
+export const ORCHESTRATOR_SYMLINK_PATH = "/usr/local/bin/hy2xs-orchestrator";
+export const RUNTIME_PACKAGE_DIR = `${ORCHESTRATOR_INSTALL_DIR}/package`;
+
+/**
+ * Каталоги пакета, которые обязаны пережить установку: reconfigure/repair/doctor
+ * работают уже от runtime-копии, а не от распакованного архива.
+ * `orchestrator/` сюда не входит намеренно — бинарник кладётся отдельно, в
+ * ORCHESTRATOR_INSTALL_PATH.
+ */
+export const RUNTIME_PACKAGE_CONTENTS: readonly string[] = [
+  "config",
+  "docs",
+  "systemd",
+  "templates",
+  "metadata",
+  "ui"
+];
+
 /** Полный machine-auth URL, который видит Hysteria. */
 export function hysteriaMachineAuthUrl(uiPort: number, machineToken: string): string {
   return `http://127.0.0.1:${uiPort}${HYSTERIA_MACHINE_AUTH_PATH}?access_token=${machineToken}`;

orchestrator/src/lib/redaction.ts

@@ -166,6 +166,56 @@ export function redactEnv(content: string): string {
     .join("\n");
 }
 
+/**
+ * Санитайз свободного текста: журналы systemd/journald, вывод `systemctl status`.
+ *
+ * У журнала нет структуры, поэтому правил ровно два и оба консервативные:
+ * всё, что разбирается как URL, проходит через sanitizeUrlValue, и отдельно
+ * ловятся пары `имя=значение` с секретоподобным именем вне URL.
+ *
+ * Без этого прохода diagnostics-бандл оставался каналом утечки: env и YAML в
+ * нём редактируются, а journal-admin.log и journal-hysteria.log копировались
+ * как есть. Пока админка логировала RequestURI, в journal-admin.log лежал
+ * machine token, и бандл уносил его наружу вместе со всем остальным.
+ * Правило синхронизировано с SanitizeLogText в apps/service/log_sanitize.go.
+ */
+const LOG_URL_PATTERN = /[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s"'<>`]+/g;
+const LOG_SECRET_ASSIGNMENT_PATTERN =
+  /([A-Za-z0-9_-]*(?:access_token|token|secret|password|passwd|passphrase|credential|api_?key|authorization|signature)[A-Za-z0-9_-]*)\s*([=:])\s*([^\s&,;"'<>`]+)/gi;
+
+const ENCODED_REDACTED = "%3Credacted%3E";
+
+function splitTrailingPunctuation(value: string): [string, string] {
+  let end = value.length;
+  while (end > 0 && ".,;:)]}!?".includes(value[end - 1] as string)) {
+    end -= 1;
+  }
+  return [value.slice(0, end), value.slice(end)];
+}
+
+export function redactLogText(content: string): string {
+  if (!content) {
+    return content;
+  }
+
+  const withSafeUrls = content.replace(LOG_URL_PATTERN, (match) => {
+    const [body, trailing] = splitTrailingPunctuation(match);
+    return `${sanitizeUrlValue(body)}${trailing}`;
+  });
+
+  return withSafeUrls.replace(
+    LOG_SECRET_ASSIGNMENT_PATTERN,
+    (match, key: string, separator: string, rawValue: string) => {
+      const [value, trailing] = splitTrailingPunctuation(rawValue);
+      if (value === REDACTED || value.toLowerCase() === ENCODED_REDACTED.toLowerCase()) {
+        return match;
+      }
+      const rendered = separator === ":" ? ": " : "=";
+      return `${key}${rendered}${REDACTED}${trailing}`;
+    }
+  );
+}
+
 /**
  * Резервный построчный проход на случай, если документ не разбирается как
  * YAML. Диагностика не должна падать, но и утекать не должна, поэтому здесь

orchestrator/src/steps/bootstrap.ts

@@ -0,0 +1,62 @@
+import type { InstallContext } from "../types/context";
+import { dirExists, fileExists } from "../lib/fs";
+import { info } from "../lib/log";
+import { runMutatingVisible } from "../lib/process";
+import {
+  ORCHESTRATOR_INSTALL_DIR,
+  ORCHESTRATOR_INSTALL_PATH,
+  ORCHESTRATOR_SYMLINK_PATH,
+  RUNTIME_PACKAGE_CONTENTS,
+  RUNTIME_PACKAGE_DIR
+} from "../config/profile";
+
+/**
+ * Первый мутирующий шаг PHASE 1: оркестратор раскладывает сам себя.
+ *
+ * Раньше это делал install.sh — между успешной PHASE 0 и запуском оркестратора.
+ * Владение мутацией при этом отследить было невозможно: shell уже создал
+ * /usr/local/lib/hy2xs, symlink и runtime-пакет, а оркестратор о них не знал и
+ * при отказе собственного preflight сообщал «на сервере ничего не изменено».
+ *
+ * Теперь у PHASE 1 один владелец. Шаг покрыт флагом ownership.bootstrapTouched,
+ * который взводится ДО вызова, поэтому частично выполненная раскладка (упал
+ * `cp` на середине, кончилось место) всё равно считается изменением хоста.
+ *
+ * Идемпотентности здесь не требуется и не имитируется: clean-host контракт уже
+ * доказал, что ни одного из этих путей на машине нет.
+ *
+ * Возвращает путь установленного runtime-пакета: дальше установка работает
+ * именно от него, а не от распакованного архива, — на сервере остаётся ровно
+ * то, из чего установка и выполнялась.
+ */
+export async function bootstrapRuntime(context: InstallContext): Promise<string> {
+  const sourcePackageDir = context.options.packageDir;
+  const sourceBinary = `${sourcePackageDir}/orchestrator/hy2xs-orchestrator`;
+
+  if (!(await fileExists(sourceBinary))) {
+    throw new Error(
+      `bootstrap: orchestrator artifact is missing in the package: ${sourceBinary}. ` +
+        "install must be started from the unpacked release package via install.sh"
+    );
+  }
+
+  await runMutatingVisible`install -d -m 0755 -o root -g root ${ORCHESTRATOR_INSTALL_DIR}`;
+  await runMutatingVisible`install -m 0755 -o root -g root ${sourceBinary} ${ORCHESTRATOR_INSTALL_PATH}`;
+  await runMutatingVisible`ln -sfn ${ORCHESTRATOR_INSTALL_PATH} ${ORCHESTRATOR_SYMLINK_PATH}`;
+
+  info(`installing runtime package assets to: ${RUNTIME_PACKAGE_DIR}`);
+  await runMutatingVisible`install -d -m 0755 -o root -g root ${RUNTIME_PACKAGE_DIR}`;
+
+  for (const entry of RUNTIME_PACKAGE_CONTENTS) {
+    const source = `${sourcePackageDir}/${entry}`;
+    if (!(await dirExists(source)) && !(await fileExists(source))) {
+      throw new Error(`bootstrap: package entry is missing: ${source}`);
+    }
+    await runMutatingVisible`cp -a ${source} ${RUNTIME_PACKAGE_DIR}/`;
+  }
+
+  // install.sh в runtime-пакет не копируется намеренно: установщик принадлежит
+  // архиву релиза, а не установленной системе. Рядом с рабочей установкой он
+  // был бы только приглашением запустить установку поверх неё.
+  return RUNTIME_PACKAGE_DIR;
+}

orchestrator/src/steps/cleanHost.ts

@@ -1,6 +1,11 @@
 import type { RuntimeConfig } from "../types/context";
 import { dirExists, fileExists } from "../lib/fs";
 import { runReadOnly } from "../lib/process";
+import {
+  ORCHESTRATOR_INSTALL_DIR,
+  ORCHESTRATOR_SYMLINK_PATH,
+  RUNTIME_PACKAGE_DIR
+} from "../config/profile";
 
 /**
  * Контракт чистого хоста для HY2XS v1.
@@ -22,19 +27,8 @@ export type LegacyMarker = {
   target: string;
   /** Человекочитаемое объяснение на русском: попадает в текст отказа. */
   description: string;
-  /**
-   * Путь, который создаёт сам install.sh в PHASE 1 до запуска оркестратора.
-   * В PHASE 0 он остаётся признаком чужой установки, в PHASE 1 — уже наш.
-   */
-  createdByInstaller?: true;
 };
 
-/**
- * PHASE 0 проверяет полный список. PHASE 1 (уже внутри `install`) исключает
- * пути, которые install.sh законно создал между фазами.
- */
-export type CleanHostPhase = "bootstrap" | "install";
-
 export type HostProbe = {
   fileExists(path: string): Promise<boolean>;
   dirExists(path: string): Promise<boolean>;
@@ -44,8 +38,15 @@ export type HostProbe = {
 /**
  * Собирает список маркеров с учётом путей из конфигурации: installDir/dataDir
  * переопределяемы, и захардкоженный список пропустил бы нестандартную установку.
+ *
+ * Деления на фазы у списка больше нет. Оно существовало, пока install.sh
+ * раскладывал оркестратор и runtime-пакет между PHASE 0 и запуском оркестратора:
+ * в PHASE 1 эти пути приходилось исключать, иначе установка отказала бы на
+ * своих же, только что созданных файлах. Теперь их создаёт сам оркестратор,
+ * уже ПОСЛЕ проверки чистоты хоста, поэтому список ровно один и означает одно:
+ * «на этой машине есть посторонняя установка».
  */
-export function legacyMarkersFor(config: RuntimeConfig, phase: CleanHostPhase = "bootstrap"): LegacyMarker[] {
+export function legacyMarkersFor(config: RuntimeConfig): LegacyMarker[] {
   const markers: LegacyMarker[] = [
     {
       kind: "file",
@@ -69,21 +70,18 @@ export function legacyMarkersFor(config: RuntimeConfig, phase: CleanHostPhase =
     },
     {
       kind: "dir",
-      target: "/usr/local/lib/hy2xs/package",
-      description: "runtime-пакет предыдущей установки HY2XS",
-      createdByInstaller: true
+      target: RUNTIME_PACKAGE_DIR,
+      description: "runtime-пакет предыдущей установки HY2XS"
     },
     {
       kind: "dir",
-      target: "/usr/local/lib/hy2xs",
-      description: "каталог оркестратора предыдущей установки HY2XS",
-      createdByInstaller: true
+      target: ORCHESTRATOR_INSTALL_DIR,
+      description: "каталог оркестратора предыдущей установки HY2XS"
     },
     {
       kind: "file",
-      target: "/usr/local/bin/hy2xs-orchestrator",
-      description: "symlink оркестратора предыдущей установки HY2XS",
-      createdByInstaller: true
+      target: ORCHESTRATOR_SYMLINK_PATH,
+      description: "symlink оркестратора предыдущей установки HY2XS"
     },
     {
       kind: "file",
@@ -149,9 +147,6 @@ export function legacyMarkersFor(config: RuntimeConfig, phase: CleanHostPhase =
 
   const seen = new Set<string>();
   return markers.filter((marker) => {
-    if (phase === "install" && marker.createdByInstaller) {
-      return false;
-    }
     const key = `${marker.kind}:${marker.target}`;
     if (seen.has(key)) {
       return false;
@@ -211,15 +206,20 @@ export function renderLegacyFailure(found: readonly LegacyMarker[]): string {
 }
 
 /**
- * Read-only проверка. Вызывается в PHASE 0 (bootstrap preflight) и повторно
- * внутри install перед первой записью состояния.
+ * Read-only проверка. Выполняется ровно дважды за установку и оба раза до
+ * первой мутации: в PHASE 0 (bootstrap preflight из распакованного пакета) и
+ * на входе в `install`, перед записью install-state.
+ *
+ * Повторять её ПОСЛЕ начала PHASE 1 нельзя: собственный
+ * /var/lib/hy2xs/install-state.json тут же станет маркером «посторонней
+ * установки». Именно это и происходило, пока clean-host был зашит внутрь
+ * preflight, а preflight вызывался ещё раз после installDeps.
  */
 export async function assertCleanHost(
   config: RuntimeConfig,
-  phase: CleanHostPhase = "bootstrap",
   probe: HostProbe = defaultHostProbe
 ): Promise<void> {
-  const found = await detectLegacyMarkers(legacyMarkersFor(config, phase), probe);
+  const found = await detectLegacyMarkers(legacyMarkersFor(config), probe);
   if (found.length > 0) {
     throw new Error(renderLegacyFailure(found));
   }

orchestrator/src/steps/networkEndpoint.ts

@@ -27,7 +27,24 @@ export type EndpointProbe = {
   getLocalPublicIpv4s(): string[];
 };
 
-export type EndpointProblemKind = "resolution" | "mismatch" | "no_local_address";
+/**
+ * Виды проблем публичного endpoint.
+ *
+ * `resolution` и `resolver_failure` разведены намеренно. Отсутствие A-записи —
+ * это ошибка конфигурации, которую чинит оператор в DNS-панели. Недоступный
+ * или отвечающий SERVFAIL резолвер — это проблема самой машины, и чинится она
+ * в /etc/resolv.conf. Раньше оба случая печатались как «has no A-record»:
+ * при сломанном резолвере оператор шёл править DNS-запись, которая на самом
+ * деле была на месте.
+ *
+ * Фатальны оба: устанавливаться с непроверенным публичным endpoint'ом продукт
+ * не должен ни в том, ни в другом случае.
+ */
+export type EndpointProblemKind =
+  | "resolution"
+  | "resolver_failure"
+  | "mismatch"
+  | "no_local_address";
 
 export type EndpointProblem = {
   kind: EndpointProblemKind;
@@ -39,10 +56,14 @@ const IPV4_PATTERN = /^(25[0-5]|2[0-4]\d|1?\d?\d)(\.(25[0-5]|2[0-4]\d|1?\d?\d)){
 /**
  * Диапазоны, которые не могут быть публичным endpoint'ом HY2XS.
  *
+ * Список приведён к IANA IPv4 Special-Purpose Address Registry, а не собран по
+ * памяти. Раньше в нём не было документационных диапазонов, и 203.0.113.5
+ * (TEST-NET-3) считался нормальным публичным адресом сервера: функция
+ * называлась «маршрутизируемый публичный IPv4», а отвечала на более слабый
+ * вопрос «не приватный ли».
+ *
  * Baseline продукта — выделенный сервер с обычным публичным IPv4; NAT и
  * Hysteria Realms описаны в документации как отдельная топология вне baseline.
- * Поэтому адрес из этих диапазонов не является ответом на вопрос «какой у
- * сервера публичный IP».
  */
 const NON_PUBLIC_IPV4_RANGES: readonly { cidr: string; description: string }[] = [
   { cidr: "0.0.0.0/8", description: "this network" },
@@ -51,11 +72,26 @@ const NON_PUBLIC_IPV4_RANGES: readonly { cidr: string; description: string }[] =
   { cidr: "127.0.0.0/8", description: "loopback" },
   { cidr: "169.254.0.0/16", description: "link-local" },
   { cidr: "172.16.0.0/12", description: "private" },
+  { cidr: "192.0.0.0/24", description: "IETF protocol assignments" },
+  { cidr: "192.0.2.0/24", description: "TEST-NET-1 (documentation)" },
+  { cidr: "192.88.99.0/24", description: "6to4 relay anycast (deprecated)" },
   { cidr: "192.168.0.0/16", description: "private" },
+  { cidr: "198.18.0.0/15", description: "benchmarking" },
+  { cidr: "198.51.100.0/24", description: "TEST-NET-2 (documentation)" },
+  { cidr: "203.0.113.0/24", description: "TEST-NET-3 (documentation)" },
   { cidr: "224.0.0.0/4", description: "multicast" },
   { cidr: "240.0.0.0/4", description: "reserved" }
 ];
 
+/** Возвращает описание диапазона, если адрес в него попадает. */
+export function nonPublicIpv4Range(value: string): string | null {
+  if (!isIpv4Literal(value)) {
+    return null;
+  }
+  const range = NON_PUBLIC_IPV4_RANGES.find((candidate) => inCidr(value, candidate.cidr));
+  return range ? `${range.cidr} — ${range.description}` : null;
+}
+
 export function isIpv4Literal(value: string): boolean {
   return IPV4_PATTERN.test(value.trim());
 }
@@ -137,19 +173,46 @@ function renderMismatch(label: string, host: string, records: readonly string[],
  * только при непустом локальном множестве, то на сервере за NAT с
  * HY2XS_PUBLIC_ENDPOINT_POLICY=off домен без A-записи прошёл бы молча.
  */
+/**
+ * Коды node:dns, означающие «имя разрешено, но записи нужного типа нет».
+ * Всё остальное — отказ самого резолвера, а не ответ про имя.
+ */
+const NO_RECORD_DNS_CODES = new Set(["ENODATA", "ENOTFOUND", "NXDOMAIN"]);
+
+function dnsErrorCode(error: unknown): string {
+  if (typeof error === "object" && error !== null && "code" in error) {
+    const code = (error as { code?: unknown }).code;
+    if (typeof code === "string") {
+      return code;
+    }
+  }
+  return "";
+}
+
+function renderResolverFailure(label: string, host: string, code: string): string {
+  return [
+    `${label}: DNS resolver failed for ${host}${code ? ` (${code})` : ""}.`,
+    "Это отказ резолвера на самой машине, а не отсутствие DNS-записи:",
+    "проверьте /etc/resolv.conf и доступность указанных в нём серверов.",
+    "HY2XS_PUBLIC_ENDPOINT_POLICY этот случай не ослабляет — без ответа",
+    "резолвера проверить публичный endpoint невозможно."
+  ].join("\n");
+}
+
 async function resolveHost(
   label: string,
   host: string,
   probe: EndpointProbe
 ): Promise<{ records: string[]; problems: EndpointProblem[] }> {
   if (isIpv4Literal(host)) {
-    if (!isRoutablePublicIpv4(host)) {
+    const reservedRange = nonPublicIpv4Range(host);
+    if (reservedRange) {
       return {
         records: [host],
         problems: [
           {
             kind: "mismatch",
-            message: `${label} ${host} is not a routable public IPv4 address`
+            message: `${label} ${host} is not a routable public IPv4 address (${reservedRange})`
           }
         ]
       };
@@ -160,11 +223,24 @@ async function resolveHost(
   let records: string[] = [];
   try {
     records = await probe.resolve4(host);
-  } catch {
-    return { records: [], problems: [{ kind: "resolution", message: `${label} has no A-record: ${host}` }] };
+  } catch (error) {
+    const code = dnsErrorCode(error);
+    if (!NO_RECORD_DNS_CODES.has(code)) {
+      return {
+        records: [],
+        problems: [{ kind: "resolver_failure", message: renderResolverFailure(label, host, code) }]
+      };
+    }
+    return {
+      records: [],
+      problems: [{ kind: "resolution", message: `${label} has no A-record: ${host}` }]
+    };
   }
   if (records.length === 0) {
-    return { records: [], problems: [{ kind: "resolution", message: `${label} has no A-record: ${host}` }] };
+    return {
+      records: [],
+      problems: [{ kind: "resolution", message: `${label} has no A-record: ${host}` }]
+    };
   }
   return { records, problems: [] };
 }

orchestrator/src/steps/preflight.ts

@@ -5,16 +5,27 @@ import { fail, info } from "../lib/log";
 import { runReadOnly } from "../lib/process";
 import { assertPlatform } from "../platform/assert";
 import { HY2XS_TARGET_ARCH, HY2XS_TARGET_DEBIAN_VERSION } from "../config/profile";
-import { assertCleanHost, type CleanHostPhase } from "./cleanHost";
+import { assertCleanHost } from "./cleanHost";
 import { checkPublicEndpoint, defaultEndpointProbe, type EndpointProbe } from "./networkEndpoint";
 
-type PreflightOptions = {
+export type PreflightOptions = {
   requireCapabilities?: boolean;
   /**
-   * bootstrap — PHASE 0, до любой мутации (полный список маркеров).
-   * install   — PHASE 1, install.sh уже разложил runtime-пакет.
+   * Проверять ли контракт чистого хоста.
+   *
+   * Это НЕ то же самое, что requireCapabilities, хотя раньше они ехали одним
+   * параметром. Чистота хоста — условие ВХОДА в операцию: она осмысленна
+   * ровно до первой мутации. Возможности платформы (systemd-run, nftables,
+   * OpenSSL 3) проверяются после installDeps, то есть уже внутри PHASE 1.
+   *
+   * Регрессия, ради которой флаг разделён: install вызывал preflight дважды и
+   * оба раза с включённым clean-host. Ко второму вызову на диске уже лежал
+   * собственный /var/lib/hy2xs/install-state.json, записанный после первого
+   * preflight, — и он опознавался как маркер посторонней установки. Каждая
+   * чистая установка падала сразу после `apt-get`, получала fatal_post_apply
+   * и оставляла сервер наполовину настроенным.
    */
-  cleanHostPhase?: CleanHostPhase;
+  checkCleanHost?: boolean;
   /** Подменяется в тестах, чтобы не зависеть от сети и интерфейсов машины. */
   endpointProbe?: EndpointProbe;
 };
@@ -23,8 +34,11 @@ type PreflightOptions = {
  * Применяет HY2XS_PUBLIC_ENDPOINT_POLICY к найденным расхождениям.
  *
  * Отсутствие A-записи фатально при любой политике: имя без A-записи не
- * работает ни в какой топологии, и ослаблять здесь нечего. Политика управляет
- * только сравнением с локальными адресами.
+ * работает ни в какой топологии, и ослаблять здесь нечего. Отказ резолвера
+ * фатален по другой причине: без его ответа проверить endpoint невозможно
+ * вовсе, и «продолжить с предупреждением» означало бы объявить проверку
+ * пройденной, не выполнив её. Политика управляет только сравнением с
+ * локальными адресами.
  */
 export async function assertPublicEndpoint(
   config: RuntimeConfig,
@@ -35,7 +49,9 @@ export async function assertPublicEndpoint(
     return;
   }
 
-  const unresolvable = problems.filter((problem) => problem.kind === "resolution");
+  const unresolvable = problems.filter(
+    (problem) => problem.kind === "resolution" || problem.kind === "resolver_failure"
+  );
   if (unresolvable.length > 0) {
     fail(unresolvable.map((problem) => problem.message).join("\n\n"));
   }
@@ -93,6 +109,17 @@ export async function preflight(context: RuntimeContext, options?: PreflightOpti
   const isReconfigure = context.mode === "reconfigure";
   const requireCapabilities = options?.requireCapabilities ?? true;
 
+  // Умолчания у checkCleanHost в режиме install нет намеренно. Любое умолчание
+  // здесь неверно: `true` ломает проход после installDeps, `false` молча
+  // выключает контракт чистого хоста у нового вызова. Решение обязано быть
+  // принято на месте вызова.
+  if (!isReconfigure && options?.checkCleanHost === undefined) {
+    throw new Error(
+      "preflight(install): checkCleanHost must be stated explicitly — " +
+        "clean-host is an entry condition of the operation, not a capability probe"
+    );
+  }
+
   const needsFirewallCapabilities = !context.options.skipFirewall &&
     context.config.firewallMode !== "off" &&
     context.config.firewallMode !== "external";
@@ -140,9 +167,10 @@ export async function preflight(context: RuntimeContext, options?: PreflightOpti
   }
 
   // Полный clean-host контракт: HY2XS v1 не устанавливается поверх другого
-  // поколения. Проверка read-only и выполняется до любой мутации.
-  if (!isReconfigure) {
-    await assertCleanHost(context.config, options?.cleanHostPhase ?? "install");
+  // поколения. Проверка read-only и выполняется только до первой мутации —
+  // см. комментарий у PreflightOptions.checkCleanHost.
+  if (!isReconfigure && (options?.checkCleanHost ?? false)) {
+    await assertCleanHost(context.config);
   }
 
   const ports = new Set([context.config.hysteriaPort, context.config.uiPort]);