Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions docs/adr/0024-owned-vpn-protocol-transitions.md
Original file line number Diff line number Diff line change
Expand Up @@ -384,6 +384,41 @@ proceeding, closing a failed final-unlink directory barrier. Read-only admission
does not synchronize or repair metadata. This backend covers native terminal
operations; schema-1 unexposed cancellation remains the separate no-op path.

## Concrete unrelated-service observation

Native completion now owns an explicit trusted observation lease: after common/WG
coordination, acquire the existing AWG then VLESS shared locks without creating
missing locks. Bind full retained private server bundles to their public source
digests before I/O, and never execute their supplied installers. Keep file,
directory, enable-link and process identities pinned through two live observations
and immutable completion publication. Historical completion replay skips this lease.

AWG retains its existing compact-JSON owner and payload marker; VLESS retains its
distinct pretty-JSON-plus-newline owner. No identifier, service or key migration is
performed. AWG compares actual private/header keys, peers and declared parameters,
ignoring only learned endpoints. Unsupported timing/security overrides refuse;
the pinned default `DisableCookies=off` is normalized. Compare actual IPv4 address,
MTU, forwarding and complete nft policy with the retained firewall compiled in a
fresh isolated network namespace, never the host ruleset.

VLESS verifies the existing installed/committed-upgrade receipt and actual process
executable, arguments, start token and cgroup. Read its loaded systemd credential
through the fixed PID mount namespace and compare exact source bytes. Accept only
systemd's owner-only read layout or its exact root-owned ACL granting read to that
dynamic UID; an unrelated reader/writer refuses. Attribute the declared listener
to that exact PID. Disk configuration or an arbitrary same-port listener alone is
insufficient. Both active and absent observations reject unexpected owner-unit
entries, including not-yet-loaded drop-ins. Absence requires complete native
namespace/listener absence and an existing coordination lock; status repairs nothing.

The pinned [AWG showconf](https://github.com/amnezia-vpn/amneziawg-tools/blob/ee0f0a9aa34ff0a0da4b3433b9512781cfe02843/src/showconf.c)
and [Go UAPI](https://github.com/amnezia-vpn/amneziawg-go/blob/b5928efb6ca19f0153958460c3d141f04abc5c2e/device/uapi.go)
define emitted configuration fields. Systemd 255
[credential handling](https://github.com/systemd/systemd/blob/v255/src/core/exec-credential.c)
defines the read-only copy and dynamic-UID access layout. These probes establish
owned configuration/service preservation, not end-to-end tunnel or media playback.
RPC and full controller/public CLI integration remain separate work.

## Private controller publication

Under the existing project lock, prepare a bounded journal containing all four
Expand Down
39 changes: 37 additions & 2 deletions docs/development/wireguard-implementation.md
Original file line number Diff line number Diff line change
Expand Up @@ -920,8 +920,8 @@ First publication holds common then WG locks and verifies the prepared generatio
actual kernel/service state and consumed history, exact installed file identities,
terminal input journal/policy and unrelated services through a trusted observer
dependency. Request JSON cannot choose that dependency. Cloud proof and local graph
attestation still belong to the controller. There is no concrete AWG/VLESS observer,
RPC or public CLI integration in this primitive. Local publication is separate below.
attestation still belong to the controller. The concrete AWG/VLESS observer is
described below; RPC and public CLI integration remain separate. Local publication is separate below.

An exact immutable schema-2 completion commits the measured historical result.
Its common head is published before retiring verified input/generation/runtime
Expand All @@ -940,6 +940,41 @@ does not perform this synchronization or repair. Deterministic fault tests cover
publication/cleanup interruptions, incomplete records, reappearing sidecars and
failed directory barriers; every service/network boundary remains synthetic.

## Leased AWG/VLESS service observation

The private concrete observer binds every retained unrelated server bundle to its
complete public source digest before guest access. It never executes a supplied
installer. Completion enters its lease under common/WG coordination, acquires
existing AWG then VLESS shared locks and retains files, directories, enable links,
PID/start tokens, arguments and cgroups through two observations and immutable
completion publication. Missing coordination is refused rather than created.
Historical completed-record recovery skips live observation.

AWG keeps its original compact-identity owner and payload marker. It compares the
actual private/header keys, exact peer policy and configured parameters, ignoring
only learned endpoints. Unsupported timing/security overrides refuse; the pinned
cookie default is normalized. It also compares IPv4 address/MTU/forwarding and
the complete native nft table with the exact retained firewall compiled in a
fresh transient network namespace. No host rule or interface is modified.

VLESS keeps its original pretty-identity owner algorithm, current owned receipt
and any verified committed runtime backup. Its exact daemon must use the declared
executable/arguments and systemd credential in its actual PID mount namespace.
Loaded credential bytes must equal the retained source, with owner-only read
permissions or the exact systemd dynamic-user read ACL; extra readers/writers
refuse. The declared TCP listener must belong to that daemon. Matching disk files
and another process's listener cannot substitute for these facts.

Both active and absent probes bound owner-unit enumeration and reject unexpected
entries, including unloaded drop-ins. Absence requires all owned files/links,
interfaces/tables and the declared listener absent, a drained unit/cgroup and an
already existing coordination lock. Existing service identifiers, keys, files and
legacy installers are preserved. Probes expose only source/receipt/absence hashes,
repair no metadata and establish no client traffic or YouTube result. Deterministic
fixtures intercept every service/process/network operation; Linux CI additionally
checks real retained AWG nft echo/list normalization in an ephemeral namespace.
Protocol RPC and full controller/public admission remain #128 work.

## Journaled local epoch publication

The private controller publisher requires caller-held project coordination. It
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
schemaVersion = 1
sourcePath = "docs/adr/0024-owned-vpn-protocol-transitions.md"
sourceHash = "sha256:69fc2e9696d9d7dbc54b378e64d1836a90ffd330c8abe04fcbdd67b2715bd67c"
reviewedTranslationHash = "sha256:73324d415942b3d94608cfd4f9707f3ffc468ddb903ea1b25952cb33254ca685"
sourceHash = "sha256:be3391f68e95e7cad1aa0ea43c506f6da93b6ad955fe180410bd152cf592e65d"
reviewedTranslationHash = "sha256:72ead84736e0f3d833c416ccca04bed2075f9f9548fa01037f80c58641bb52d0"
reviewer = "Codex"
reviewerType = "ai"
reviewedAt = "2026-11-07T09:44:22.875277Z"
reviewedAt = "2026-11-07T10:28:27.601352Z"
reviewRoles = ["editorial", "technical"]
body = '''# ADR 0024: Управляемые переходы VPN-протоколов и неизменяемые эпохи

Expand Down Expand Up @@ -275,6 +275,40 @@ vendor-CVE, закреплённой сборки инструмента и ко
не синхронизирует и не исправляет метаданные. Backend покрывает нативные конечные
операции; отмена схемы 1 до внешней отправки остаётся отдельным путём без изменения.

## Конкретное наблюдение остальных служб

Нативное завершение теперь удерживает явную доверенную аренду наблюдения: после
общей/WG координации получает существующие общие блокировки AWG, затем VLESS, не
создавая отсутствующие. Полные приватные серверные пакеты связываются с публичными
хешами источников до ввода-вывода; переданные установщики не исполняются. Идентичности
файлов, каталогов, ссылок включения и процессов закреплены на время двух живых
наблюдений и записи неизменяемого завершения. Исторический повтор аренду не получает.

AWG сохраняет прежний owner из компактного JSON и маркер пакета; VLESS — отдельный
owner из форматированного JSON с переводом строки. ID, службы и ключи не мигрируют.
AWG сравнивает реальные приватный/header ключи, клиентов и объявленные параметры,
исключая лишь изученные Endpoint. Неподдерживаемые тайминги/security overrides
отклоняются; закреплённое `DisableCookies=off` нормализуется. Реальные IPv4-адрес,
MTU, forwarding и вся nft-политика сверяются с сохранённым firewall, скомпилированным
в новом изолированном сетевом пространстве имён, не в правилах хоста.

VLESS проверяет установленную квитанцию/подтверждённый runtime-upgrade, реальный
исполняемый файл, аргументы, start token и cgroup процесса. Загруженный systemd
credential читается через фиксированное mount namespace PID и сравнивается с
точными исходными байтами. Допустимы только чтение владельцем либо точный root-owned
ACL, дающий чтение данному динамическому UID; лишние читатели/запись отклоняются.
Слушатель заявленного порта обязан принадлежать этому PID. Одних файлов на диске
или чужого слушателя того же порта недостаточно. Активное состояние и отсутствие
отклоняют неожиданные записи unit владельца, включая ещё не загруженные drop-in.
Отсутствие требует полного отсутствия нативного пространства/слушателя и прежнюю
блокировку координации. Status ничего не исправляет.

Поля вывода определяют закреплённые [AWG showconf](https://github.com/amnezia-vpn/amneziawg-tools/blob/ee0f0a9aa34ff0a0da4b3433b9512781cfe02843/src/showconf.c)
и [Go UAPI](https://github.com/amnezia-vpn/amneziawg-go/blob/b5928efb6ca19f0153958460c3d141f04abc5c2e/device/uapi.go).
Read-only копию и доступ динамического UID определяет [обработка credentials systemd 255](https://github.com/systemd/systemd/blob/v255/src/core/exec-credential.c).
Эти проверки подтверждают сохранение управляемой конфигурации/службы, но не сквозной
трафик туннеля или воспроизведение видео. RPC, координатор и публичный CLI ещё требуют интеграции.

## Приватная публикация контроллера

Под существующей блокировкой проекта до запроса завершения гостя сохраняется
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
schemaVersion = 1
sourcePath = "docs/development/wireguard-implementation.md"
sourceHash = "sha256:544048731e7d4cc36d5b4500d2e1b2342e157b92700b5193628b47f8f63a5073"
reviewedTranslationHash = "sha256:0a09ed24af51a7d0c6cd9f7667e89bbc79b0d2b0feb425420c748a3b65f36473"
sourceHash = "sha256:f124167191e9aa065818340ebb3a2c09887e401e49f43a552fca2e967a979ac9"
reviewedTranslationHash = "sha256:a223142f70eb5ec427bf96c4f012ab67629b59f66aff49dc2a683e4ef6ccc313"
reviewer = "Codex"
reviewerType = "ai"
reviewedAt = "2026-11-07T09:44:20.768529Z"
reviewedAt = "2026-11-07T10:28:25.996946Z"
reviewRoles = ["editorial", "technical"]
body = '''# Границы реализации стандартного WireGuard

Expand Down Expand Up @@ -815,8 +815,8 @@ JSON. Восстановление окончательно выводит ст
фактическое ядро/службу и израсходованную историю, точные идентичности установленных
файлов, конечные входные журнал/политику и остальные службы через доверенный observer.
JSON запроса не выбирает эту зависимость. Облачная аттестация и локальный граф остаются
обязанностью координатора. Конкретный AWG/VLESS observer, RPC и интеграция публичного
CLI в этом примитиве отсутствуют. Локальная публикация описана отдельно ниже.
обязанностью координатора. Конкретный AWG/VLESS observer описан ниже; RPC и публичный
CLI ещё требуют интеграции. Локальная публикация описана отдельно ниже.

Точная неизменяемая запись схемы 2 фиксирует измеренный исторический результат.
Общая голова публикуется перед удалением проверенных журналов input/generation/runtime,
Expand All @@ -836,6 +836,40 @@ runtime-файлы не перечисляются и не удаляются.
и очистки, неполные записи, повторное появление журналов и сбои каталожных барьеров;
все сервисные/сетевые границы остаются синтетическими.

## Наблюдение AWG/VLESS с удержанием аренды

Приватный observer связывает каждый полный сохранённый серверный пакет остальных
протоколов с его публичным хешем до доступа к гостю. Переданный установщик никогда
не исполняется. Завершение получает аренду под общей/WG координацией, затем существующие
общие блокировки AWG и VLESS; файлы, каталоги, ссылки включения, PID/start tokens,
аргументы и cgroup закреплены на время двух наблюдений и неизменяемой публикации.
Отсутствующая блокировка отклоняется, не создаётся. Историческое завершение
восстанавливается без живого наблюдения.

AWG сохраняет исходный owner компактного JSON и маркер пакета. Сверяются реальные
приватный/header ключи, точная политика клиентов и настроенные параметры; исключаются
только изученные Endpoint. Необъявленные тайминги/security overrides отклоняются;
закреплённый cookie default нормализуется. Также сверяются IPv4-адрес/MTU/forwarding
и полная нативная nft-таблица с точным сохранённым firewall, скомпилированным в новом
временном сетевом namespace. Правила и интерфейсы хоста не изменяются.

VLESS сохраняет прежний owner форматированного JSON, текущую квитанцию и проверенный
подтверждённый runtime backup. Его процесс обязан использовать точные исполняемый
файл/аргументы и systemd credential в реальном mount namespace PID. Загруженные байты
равны источнику; доступны лишь owner-only чтение или точный ACL чтения динамического
UID systemd. Лишние читатели/запись отклоняются. Заявленный TCP-слушатель принадлежит
этому процессу. Совпадение файлов на диске и чужой слушатель не заменяют эти факты.

Активное состояние и отсутствие ограничивают обход unit и отклоняют неожиданные
записи, включая незагруженные drop-in. Отсутствие требует отсутствия управляемых
файлов/ссылок, интерфейсов/таблиц и заявленного слушателя, завершённый unit/cgroup
и уже существующую блокировку. Прежние ID служб, ключи, файлы и установщики сохраняются.
Наблюдение выдаёт только хеши источника/квитанции/отсутствия, не исправляет метаданные
и не подтверждает трафик клиента или YouTube. Детерминированные фикстуры перехватывают
все сервисные/процессные/сетевые операции; Linux CI дополнительно сверяет настоящее
AWG nft echo/list в эфемерном namespace. RPC и полный координатор/публичный допуск
остаются работой #128.

## Журналируемая локальная публикация эпохи

Приватный publisher контроллера требует удерживать блокировку проекта. До завершения
Expand Down
Loading
Loading