Add server configuration editing with byte preservation

2026-10-18 22:34:01 +03:00
parent c2b899dd1e
commit 766059e6d1
11 changed files with 2521 additions and 19 deletions
@@ -0,0 +1,98 @@
+# Managed metadata in the WireGuard configuration
+
+WireGuard Admin stores a client's display alias and optional creation time in a
+versioned comment block immediately before that client's `[Peer]` header. The
+server configuration remains the source of truth. The block contains no public
+key copy, private key, preshared key, password, or other connection secret.
+
+## Version 1 grammar
+
+The canonical LF form is:
+
+```ini
+# wg-admin:begin
+# wg-admin:version=1
+# wg-admin:alias=<base64url-utf8-without-padding>
+# wg-admin:created-utc=2026-10-18T19:00:00Z
+# wg-admin:end
+[Peer]
+```
+
+`created-utc` is optional. If it is unknown, it is omitted; an existing peer's
+unknown creation date is never inferred from import time, file time, or edit time.
+The timestamp grammar is exactly `YYYY-MM-DDTHH:MM:SSZ`, with a real Gregorian
+calendar date, a four-digit nonzero year, and seconds from `00` through `59`.
+Leap seconds and fractional seconds are not represented.
+
+The alias line contains the canonical URL-safe Base64 encoding of the alias's
+UTF-8 bytes, with no `=` padding. This representation is a single comment line
+and makes characters such as `#`, `=`, quotes, non-ASCII text, and strings that
+look like block markers unambiguous. An alias must pass the application's shared
+alias validation: it cannot be empty or contain Unicode control characters.
+The encoded representation is decoded and re-encoded canonically when read.
+
+The v1 block has exactly one begin marker, one version field, one alias field,
+optional single creation field, and one end marker, in the displayed order. No
+other lines or fields are permitted. Unknown fields, duplicate fields, malformed
+encoding, or invalid timestamps make the block invalid. A version other than 1
+is reported as unsupported and is not interpreted or rewritten.
+
+## Ownership and attachment
+
+The exact reserved marker lines are `# wg-admin:begin` and `# wg-admin:end`.
+Marker lines with trailing whitespace or extra text are treated as malformed
+reserved markers. Other administrator comments, including comments that merely
+mention `wg-admin`, do not become managed blocks.
+
+A valid block owns only its own comment lines and line endings. It is attached to
+one peer only when its end marker line, including its line ending, ends at the
+first byte of that peer's `[Peer]` header. No blank line, administrator comment,
+or other text may intervene. A block elsewhere is reported as misattached. A
+missing block is the legacy state: no alias or creation date is inferred, and no
+block span is available to edit. Multiple adjacent blocks before one peer are a
+duplicate and block metadata edits. Malformed, misattached, duplicate, and
+unsupported-version blocks are retained as supplied and block unsafe metadata
+edits; they are not treated as absent metadata.
+
+The parser exposes the decoded alias only for a valid, uniquely attached v1
+block. It exposes an owned byte span only for that valid block. Issues contain
+line numbers and categories but never raw source text. Parsing and rendering are
+caller-buffer operations and do not read or write configuration files.
+
+## Examples
+
+An alias containing syntax characters and Unicode is encoded, not escaped in
+WireGuard syntax. For example, the alias `# café = "laptop"` is represented as:
+
+```ini
+# wg-admin:begin
+# wg-admin:version=1
+# wg-admin:alias=IyBjYWbDqSA9ICJsYXB0b3Ai
+# wg-admin:end
+[Peer]
+```
+
+A marker-looking alias is handled the same way. Applications should use the
+canonical renderer rather than hand-constructing the encoded value.
+
+An existing client with unknown creation time has no `created-utc` field:
+
+```ini
+# wg-admin:begin
+# wg-admin:version=1
+# wg-admin:alias=V29ya2xhcGU
+# wg-admin:end
+[Peer]
+PublicKey = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
+AllowedIPs = 10.0.0.2/32
+```
+
+An unrelated administrator comment is preserved and does not describe managed
+metadata:
+
+```ini
+# Added during the 2024 network migration; wg-admin is not the owner of this note.
+[Peer]
+PublicKey = AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE=
+AllowedIPs = 10.0.0.3/32
+```