chore(server): checkpoint deployed services and unfinished forums

User requested a checkpoint and stopped all agents. Deployed artifacts remain the last verified releases; unfinished settings/categories/forums are preserved as WIP. See TODO/roadmap for verification and remaining release/updater work.
This commit is contained in:
Loki 2026-11-01 15:31:20 +01:00
parent d6d406bbf5
commit c18ccadf99
Signed by: boba
GPG key ID: 253067914055423B
96 changed files with 8665 additions and 276 deletions

View file

@ -29,7 +29,7 @@ encryption, routing, identity, and federation.
## Version
Current version: `LNEx v3` (TCP runs inside TLS 1.3, see [tls.md](tls.md)). There is no negotiation with older versions.
Current version: `LNEx v4` (TCP runs inside TLS 1.3 and requires a Central account proof; see [tls.md](tls.md) and [central-account.md](central-account.md)). There is no negotiation with older versions.
Version is negotiated during handshake. Clients and servers advertise
their supported versions. If no common version exists, the connection
@ -83,4 +83,4 @@ Full state machine: see individual spec files.
- [federation/README.md](federation/README.md) — node discovery, cross-node routing
- [identity.md](identity.md) — keypair model, auth flow, permissions
- [security.md](security.md) — encryption, threat model
- [tls.md](tls.md) — TLS 1.3 control plane, trust model, LNEx v3 handshake
- [tls.md](tls.md) — TLS 1.3 control plane, trust model, LNEx v4 handshake

View file

@ -0,0 +1,54 @@
# Account presence and profiles
LNEx v4 additive metadata: MemberInfo fields 4 account_id and 5 avatar_url; UserJoin fields 4 account_id and 5 avatar_url. user_id remains the authenticated Ed25519 device key, never an account UUID. Channel memberships and UDP routes retain their session IDs. Snapshots include each device once; repeated sessions on the same device emit UserLeave only after the last subscription leaves. Presence OFFLINE is emitted only after the last session of that device closes. Clients group member rows by nonempty account_id while retaining all device IDs for voice attribution, and remove only the leaving device.
Central v1 signed proof claims optionally include display_name and avatar_url. Names are bounded to 64 characters; avatar URLs are relative /v1/avatars/ paths, resolved only against https://central.loki-code.dev. Gateway ignores unsigned client nickname when a signed profile exists. Missing optional fields retain compatibility with existing proofs. Avatar HTTP requests have no auth/cookies, reject redirects, bound response and dimensions, and execute outside the UI thread. Default avatar paths use the authenticated account UUID. No database migration, ownership reassignment or protocol version change is required.
## Desktop avatar mutation and live summary refresh
`POST /v1/auth/desktop/avatar` uploads a cropped raw PNG (image/png, at most 2 MiB); `DELETE` on the same path uses an empty body. Both use Authorization: Bearer <desktop refresh secret>, X-Vnox-Public-Key (lowercase Ed25519 hex), X-Vnox-Timestamp (Unix seconds), and X-Vnox-Signature (hex Ed25519). Signature bytes cover `VNOX-CENTRAL-PROFILE-v1\0` followed by method ASCII, NUL, request path ASCII, NUL, decimal timestamp ASCII, NUL, then SHA-256(raw body). Timestamp skew is bounded to 60 seconds. Hub verifies the active unexpired enrollment matches the supplied key and account; cookies are never used. Replays within that window repeat the identical idempotent image/delete mutation. Existing avatar normalization, per-account/per-source budgets, bounded decoding and immutable content IDs apply. Success returns `{user: AccountSummary}` with effective same-origin avatar path. No schema migration is required.
Desktop refresh responses already return `user`; clients now validate subject consistency, atomically persist it only if the same enrollment remains active, and publish a non-secret profile update to UI. Admission, startup, periodic refresh and opening profile settings obtain current Central data. Mutation results use the same update path. Late network results cannot restore credentials or avatars after sign-out. Public PNG requests remain separate and never carry enrollment headers.
`POST /v1/auth/desktop/profile` uses the same enrollment headers and signature (including its distinct path) with JSON `{display_name: string}` limited to 1024 bytes. The trimmed name must contain 1–64 characters and no control/bidi override characters. Only existing accounts.display_name changes; handle, account UUID, device ID, roles and profile_complete remain unchanged. Account/source profile rate limits apply. Success returns `{user: AccountSummary}` and clients persist/publish it exactly like avatar changes. Signed proofs carry the new display name on admission and through the additive live update described below. No protocol version change is introduced.
## Live signed profile updates
LNEx v4 additive packets: `0x0042 ProfileUpdate { bytes account_proof = 1; }` (client to gateway), `0x0043 ProfileUpdated { string user_id = 1; string account_id = 2; string nickname = 3; string avatar_url = 4; int64 issued_at = 5; }` (gateway to client). Gateway verifies the Central issuer signature, lifetime, audience and device binding exactly as admission, and requires the subject to equal the current session account. Display name and avatar must be valid signed profile claims. No client-supplied unsigned nickname/avatar is accepted. Existing Ed25519 device keys, channel/session membership, ownership, permissions and UDP credentials stay unchanged.
The newest accepted issued_at among active sessions of an account prevents older proofs downgrading metadata. Equal-second proofs are accepted (Central proof timestamp resolution is one second); same-second cosmetic ordering is last-arrival. This is transient display metadata, not authorization. Gateway updates profile fields on account sessions and emits each affected device's ProfileUpdated only to its own sessions or peers currently sharing its text/voice channel. Delivery rechecks that visibility; no node-wide profile broadcast or join/leave event is generated.
Desktop forwards the proof obtained by its existing Central refresh; profile-only mutation notifications trigger one coalesced background refresh, not a refresh loop. Before chat/image send or channel/voice join, a proof older than five seconds causes those actions to wait for one bounded refresh; audio/UDP, incoming packets and keepalives continue. ProfileUpdate is written before the actions on the same TCP stream. A failed Central refresh leaves the gateway/voice session active, reports failure, and sends the action with its last verified profile. Opening settings and periodic refresh also propagate signed updates live. No reconnect is required.
## Registration display names and web onboarding
New accounts receive one locally generated friendly Russian word plus `_` and four
cryptographically random decimal digits. Neither email local parts nor GitHub names
become public defaults. Existing account names and immutable handle selection are
unchanged. Word data and its license ship with Hub; no network lookup occurs during
registration.
Migration 0009 adds an independent account_onboarding table. Only newly created
accounts receive pending rows; existing accounts do not acquire a prompt. Session
responses add optional top-level onboarding_pending. POST /v1/account/onboarding
accepts {decision:"rename"|"later"}, records an explicit choice once, and never
changes handle/name. POST /v1/account/display-name accepts {display_name:string},
updates only the existing display_name column, resolves a pending prompt as an
explicit rename, and returns {display_name,onboarding_pending:false}. Both routes
require the same own-origin cookie session and CSRF protection as avatar changes,
small JSON bodies, and per-account/source profile budgets. They do not depend on
pending migration 0006 or require LNEx changes.
## Explicit node administrator capability
Node operators may set `[gateway] admin_account_ids = ["<Central account UUID>"]`. The default empty list grants nobody node administration. Startup rejects invalid/nil UUIDs, duplicates and more than 256 entries. Only the verified Central subject on the authenticated Session is compared with this list; nickname and device public key never confer this role. This is a static operator setting, applied on daemon restart/admission, not first-visitor ownership.
Session gains additive `bool node_admin = 4`, advertising global channel management capability to clients. A listed account may create, rename and delete global (guild_id absent) channels; its other admitted devices receive the same capability. `general` and `voice` remain undeletable bootstrap IDs. Guild ownership/membership/role checks remain unchanged: node administrator status cannot create/edit/delete another guild's channels or bypass voice access. Server checks actual stored channel scope for edit/delete, never a client claim. Clients expose global management controls only for advertised capability and still handle gateway denial.
Global channel metadata changes are visible to all authenticated node sessions; guild metadata remains restricted to persisted guild members. Created/renamed channels are persisted through the existing storage bootstrap path. No database/protocol version migration is required.
Deferred activity is scoped to one TCP session, limited to 32 actions and 4 MiB total contents. Duplicate joins coalesce. Explicit leave cancels matching deferred activity; disconnect/server switch clears it, and session scope drop aborts the HTTP refresh task. Nothing is replayed into another node or session.
### Gateway capability negotiation
Session field 5 `bool live_profiles` is true on gateways supporting packets 0x0042/0x0043. Absent/false on older LNEx v4 gateways: desktop must not send ProfileUpdate, start activity-triggered profile HTTP refresh, or defer chat/image/join for it. Normal existing activity packets continue directly. The local Central profile UI can still refresh independently. This explicit opt-in preserves additive compatibility with older v4 gateways that reject unknown packet IDs.

View file

@ -0,0 +1,48 @@
# LNEx v4: mandatory Central account admission
LNEx v4 requires a Central account proof in AUTH (field 6, `bytes account_proof`).
There is no anonymous or private-mode exemption. v3 clients and gateways must be
upgraded together. TLS 1.3 and existing channel-bound Ed25519 signatures remain;
v4 changes their domain separator from `VNOX-LNEx-v3-` to `VNOX-LNEx-v4-`.
The proof is UTF-8 JSON `{ "claims": "<hex>", "signature": "<hex>" }`.
Claims are the exact UTF-8 JSON bytes (hex encoded), containing `version` (1),
`issuer` (Hub issuer UUID), `subject` (Central account UUID), `public_key` (lowercase
hex desktop Ed25519 key), `issued_at` and `expires_at` (Unix seconds), and
`audience` (`vnox-gateway`). The Hub Ed25519 signature covers the bytes
`VNOX-CENTRAL-ACCOUNT-v1\0` followed by the decoded claims. Gateways use explicitly
configured trusted issuer UUID/public key, never keys supplied by clients or
fetched from arbitrary URLs. They reject missing, malformed, expired, future,
overlong-lived (>600 seconds), wrong-audience, unknown-issuer and incorrectly
signed proofs, and require the subject key to equal AUTH's client public key.
AUTH's channel-bound signature includes the proof. Gateways verify before storage
or session creation. Proofs authorize new admission for ten minutes; revoking a
device stops refresh immediately, while already issued proofs expire naturally.
Existing gateway session timeout remains independent of the admission proof.
## Browser device authorization
Desktop POSTs `/v1/auth/desktop/start` with only its public key. The Hub returns a
256-bit device secret, separate random user code, expiry (600 seconds), and a
same-origin browser URL `/desktop?code=...`. Only the user code enters the browser;
no private identity key, device secret or account proof appears in URLs. The
browser uses the existing real email/GitHub Central login. It displays the key
fingerprint and requires explicit approval with the normal session cookie,
exact-Origin and session-CSRF checks. An authenticated user's approval binds the
request to that account; approval never creates a synthetic account. Desktop
polls `/v1/auth/desktop/poll` with its device secret; pending is HTTP 202, expired
or canceled requests fail closed. Approval yields the signed proof and a long
random refresh secret. Secrets are stored only as SHA-256 hashes on Hub. Polling
completion is single-use, so a captured browser code cannot retrieve credentials.
Desktop cancellation deletes the pending request. Device enrollment expires after
30 days; refresh checks that enrollment is still live and issues a new short proof.
Desktop logout disables local admission immediately by atomically moving credentials
to a private revocation tombstone; online revocation removes it. Network failures
retain the admission-disabled tombstone, retried on later sign-in/admission. HTTPS is required
for all desktop Central calls; redirects are disabled and request timeouts bounded.
Desktop local credential storage uses a private directory and 0600 file, bound to
the local identity public key. The local Ed25519 private key never leaves desktop.
Rate limits and bounded request bodies apply. Expiry is checked on every operation;
cleanup does not replace authorization checks. HTTP responses use no-store. All
browser approval actions are explicit POSTs; GET requests never approve devices.

View file

@ -0,0 +1,9 @@
# Channel image attachments (additive LNEx v4 extension)
Written before implementation. Existing packets and protobuf field numbers remain unchanged; no protocol version bump is needed. Unknown packet IDs remain ignorable. Voice messages and DM attachments are outside this extension.
Authenticated TLS sessions may send AttachmentUpload (0x0220): request_id=1 string, channel_id=2 string, data=3 bytes. The gateway validates PNG/JPEG/GIF content (maximum 3 MiB encoded; dimensions <=4096 each; <=4 million pixels and <=120 frames and <=8,388,608 aggregate frame pixels (32 MiB RGBA)), enforces upload rate and durable per-sender 64 MiB / global 512 MiB quotas (also 10,000 attachments per sender and 100,000 overall to bound row metadata), and requires the session to be currently joined to the channel. Success durably stores bytes in the existing authenticated database and posts an ordinary chat message `vnox-attachment:<server UUID>`. Such a marker identifies an attachment only within its message channel, never a filesystem path or public URL.
AttachmentFetch (0x0221): request_id=1, channel_id=2, attachment_id=3 strings. The current session must be joined to that exact channel; lookup is scoped by channel and ID. AttachmentResult (0x0222): request_id=1, channel_id=2, attachment_id=3, mime=4 strings, data=5 bytes, error=6 string. Upload responses omit bytes; fetch responses carry validated bytes. Errors carry a bounded human-readable error and no bytes. All traffic uses the existing TLS frame transport; 3 MiB binary protobuf remains below its 4 MiB frame limit. No HTTP listener, bearer URL, cookies, or externally accessible storage is introduced.
Images are validated off the async runtime with at most two concurrent validations per gateway process. Quota check, byte insertion, chat history and outgoing webhook events commit in one database transaction, serialized using the existing SQLite write lock / PostgreSQL advisory transaction lock across gateway processes. Current channel existence, text kind and guild membership are revalidated under the access lock; uploads additionally require MESSAGE_SEND (owner/administrator override). Uploads use the existing chat-send rate limiter. Fetches have a separate per-session budget (50 initial requests, refilling at four per second), stored in the same session entry and removed on disconnect, so opening history cannot consume chat-send tokens. Existing channel history preserves the marker and stored bytes survive restarts. Attachments currently have no automatic eviction; quota exhaustion returns an error. Deleting a message does not free its attachment immediately. Clients must bound decoding/cache and explicitly confirm clipboard previews before uploading. Direct HTTPS image URLs are a separate client capability and must not bypass private-network or redirect protections.

View file

@ -0,0 +1,31 @@
# Node settings, structured channels and forums (LNEx v4 additive)
## Plan and compatibility
Implement persisted public node name/description, one-level channel categories and actual forum topics/replies. Authorization uses the verified Central account/session and existing guild permissions. Existing channels/messages/ownership/voice keys remain intact. Storage extends gateway SQLite/PostgreSQL idempotently, independently of Hub migrations.
Session advertises `node_settings` (6), `channel_structure` (7), `forums` (8). A capable desktop sends `0x0232 ClientFeatures {node_settings=1,channel_structure=2,forums=3}` after Session, before channel listing/actions, only when the corresponding server flag is true. No AUTH fields are added: older v4 signature verification re-encodes AUTH and would drop unknown fields. Older clients never report features: new category/forum kinds are hidden from their channel lists and metadata delivery; existing text/voice remain usable. New clients talking to old gateways disable unsupported controls/packets.
## Settings
`0x0230 NodeSettingsRequest {request_id=1,update=2,display_name=3,description=4}`. `0x0231 NodeSettingsResult {request_id=1,display_name=2,description=3,error_code=4,error=5}`. Reads return public data to authenticated clients; updates require the exact session's configured node-admin Central UUID. Name is trimmed, 1–100 characters, no control/bidi override characters. Description is trimmed, at most 2000 characters, permits newline/tab but no other controls/bidi overrides. Success persists before ACK and updates HELLO's node name; future restarts use the stored name/description, config name is only an initial fallback. Changes broadcast Result with empty request_id to feature-capable authenticated clients. Errors are correlated Results, never unrelated join errors.
## Categories and layout
Channel kinds are `text`, `voice`, `category`, `forum`. Add parent_id/position to ChannelCreate (5/6), ChannelState (7/8), ChannelListItem (5/6); ChannelEdit optionally changes parent_id (3) and position (4), absent means unchanged, present empty parent means detach to root. Position is 0–1000000, stable ties use channel ID. Categories always live at root; a child's parent must be an existing category in the exact same global/guild scope. No nested categories, cycles, cross-guild parents or implicit channel replacement.
Node administrators manage global structure; guild management still requires the existing owner/MANAGE_CHANNELS policy. Category JoinChannel is rejected before changing current text/voice subscriptions. Forum JoinChannel is view-only (no generic chat history, audio or UDP credentials). Deleting a category atomically reparents children to root and deletes only the grouping metadata. Bootstrap general/voice IDs remain undeletable. A forum containing any topic cannot be deleted; guild deletion containing forum topics is also refused, preserving discoverability and all replies.
## Forums
`0x0240 ForumRequest`: request_id (1), ForumOperation operation (2), channel_id (3), topic_id (4), title (5), content (6), offset (7), limit (8), message_id (9). Enum UNSPECIFIED=0, LIST=1, CREATE=2, OPEN=3, REPLY=4.
`0x0241 ForumResult`: request_id (1), operation (2), channel_id (3), topic_id (4), topics (5), posts (6), has_more (7), error_code (8), error (9). Every response/error is correlated. `0x0242 ForumChanged`: channel_id (1), topic (2), post (3), broadcast only to current authorized forum subscribers and rechecked at delivery.
ForumTopic: topic_id (1), channel_id (2), title (3), MemberInfo author (4), created_at (5), updated_at (6), reply_count (7). ForumPost: ChatMessage message (1), MemberInfo author (2), topic_id (3), uint64 ordinal (4). Author IDs/account/name/avatar originate solely from the authenticated verified session. Snapshot names/avatar allow offline authors; clients retain newer live profile cache entries when displaying snapshots.
LIST defaults to 20, maximum 50 topics; OPEN defaults to 50, maximum 100 posts; offsets at most 100000. Handler fetches limit+1 to determine has_more. Titles are trimmed, 1–160 characters, without control/bidi overrides. Bodies are trimmed, 1–16000 characters and at most 64 KiB, newline/tab permitted. CREATE requires stable client UUID topic_id and message_id; REPLY requires stable message_id. Retries reuse IDs and must match channel/topic/author device+account/title/body to be idempotent; conflicts fail without linking unrelated/private messages. Topic and first message commit atomically. Per-topic ordinal guarantees deterministic reply order even within one millisecond.
Posts reuse existing messages under the forum channel ID plus an explicit topic mapping. Reads always constrain both channel and topic. Generic chat sends/history, message edits/deletes/reactions and attachment uploads do not mutate forum posts; dedicated ForumRequest is the only posting API in this scope. No topic/post deletion is exposed. Forum access requires node-global visibility or guild membership; guild posting additionally requires owner/MESSAGE_SEND, node administration does not bypass guild policy. Rate limits and shared-access guards protect posting versus concurrent channel/access changes. CREATE/REPLY clients refresh signed profile through the existing bounded activity queue, without interrupting voice.
All deferred administrative or forum actions are fenced to the authenticated client session so queued operations cannot execute on a different node after switching.

View file

@ -1,6 +1,6 @@
# Security
> **LNEx v3 status.** TCP traffic runs over TLS 1.3.
> **LNEx v4 status.** TCP traffic runs over TLS 1.3.
> UDP voice path is still plaintext (Phase 2). See
> [features/encryption.md](../05-features/encryption.md) for details.
@ -31,7 +31,7 @@ The threat model covers:
## Encryption
TCP control traffic is protected by **TLS 1.3** (rustls, ALPN `vnox-lnex/3`). The earlier
TCP control traffic is protected by **TLS 1.3** (rustls, ALPN `vnox-lnex/4`). The earlier
LNEx v2 per-frame ChaCha20-Poly1305 layer is removed. Trust model, certificate handling,
channel binding and version bump: see [tls.md](tls.md).
@ -116,3 +116,7 @@ temporary ban depending on node configuration.
- rotate node keypair on suspected compromise
See `03-server/operations.md` for hardening checklist.
LNEx v4 additionally requires a short-lived, issuer-signed Central account proof
bound to the client Ed25519 key, before any session or user write. Private mode
has the same requirement. See [Central account admission](central-account.md).

View file

@ -1,8 +1,10 @@
# TLS 1.3 for the TCP control plane (LNEx v3)
# TLS 1.3 for the TCP control plane (LNEx v4)
> Status: design accepted and implemented together with this document.
> Current version: LNEx v4. TLS was introduced in v3; v4 adds mandatory
> [Central account admission](central-account.md), preserving the TLS security model.
> This document describes the current v4 transport parameters.
> This is a **breaking change**: LNEx v2 (custom X25519 + HKDF + ChaCha20-Poly1305
> layer on TCP) is removed. The protocol version is bumped to `v3`.
> layer on TCP) is removed. The protocol version is bumped to `v4`.
> UDP voice is **not** affected (see [Voice](#voice-udp-is-unchanged)).
## Goals
@ -27,7 +29,7 @@
| # | Decision |
|---|----------|
| D1 | `rustls` 0.23 with the `aws_lc_rs` provider, **TLS 1.3 only** on both sides. ALPN `vnox-lnex/3` is required. |
| D1 | `rustls` 0.23 with the `aws_lc_rs` provider, **TLS 1.3 only** on both sides. ALPN `vnox-lnex/4` is required. |
| D2 | The server certificate is either user supplied (`tls_cert_path` / `tls_key_path`, for example Let's Encrypt) or **auto generated** on first start and stored in `data_dir/tls/self-signed.pem`. |
| D3 | The auto generated certificate uses the **server identity Ed25519 key as its TLS key**. Therefore the certificate fingerprint is a pure function of the identity key, survives certificate regeneration, and no second private key is stored. |
| D4 | The **pin** is `SHA-256(SubjectPublicKeyInfo DER)` of the leaf certificate (the "SPKI fingerprint"). It is the trust anchor for self-signed servers. |
@ -35,7 +37,7 @@
| D6 | A changed fingerprint is a **hard block** with a warning. There is no "connect anyway". The only way forward is an explicit "forget this server" followed by a new trust decision. |
| D7 | The Ed25519 client authentication stays, but its signature covers a **TLS exporter value (channel binding)**, so it cannot be relayed over another TLS connection. The server HELLO is signed with its identity key over the same binding. |
| D8 | The X25519 + HKDF + ChaCha20-Poly1305 layer on TCP, the `ENCRYPTED` packet flag on TCP and the ephemeral key fields in `Hello` and `Auth` are removed. |
| D9 | LNEx version is bumped from `v2` to `v3`. Old clients and old servers fail with an explicit error. Downgrade is impossible by construction. |
| D9 | LNEx version is bumped from `v2` to `v4`. Old clients and old servers fail with an explicit error. Downgrade is impossible by construction. |
## Threat model
@ -45,7 +47,7 @@
| Active MITM terminating TLS with its own certificate | Pin mismatch (known server) or TOFU prompt showing a different fingerprint (new server). Even if the user accepted a wrong fingerprint, the MITM cannot produce the server's Ed25519 signature over this connection's exporter, and the client rejects a server identity that differs from the stored one. |
| MITM relaying the server's HELLO to the client | HELLO signature covers the exporter of the TLS session between the client and the relay, which differs from the relay to server session. Verification fails. |
| Malicious server relaying a client's AUTH to another server | AUTH signature covers the exporter of the connection to the malicious server. Another server computes a different value and rejects it. |
| Downgrade to plaintext, TLS 1.2 or LNEx v2 | The client never opens a plaintext socket, the rustls configs list only TLS 1.3, the server requires ALPN `vnox-lnex/3`, and the version string `v3` is inside the signed transcripts. |
| Downgrade to plaintext, TLS 1.2 or LNEx v2 | The client never opens a plaintext socket, the rustls configs list only TLS 1.3, the server requires ALPN `vnox-lnex/4`, and the version string `v4` is inside the signed transcripts. |
| First connection MITM (TOFU weakness) | Unavoidable without a CA or out of band data. Mitigation: the server prints its fingerprint at startup and writes it to `data_dir/tls/fingerprint.txt`; owners should publish it with the invitation, users compare before confirming. Public CA certificates skip TOFU. |
| Compromised or replaced server key | Fingerprint changes, clients block (D6). |
@ -82,7 +84,7 @@ At startup the gateway logs `TLS SPKI SHA-256 fingerprint: <hex>` and writes it
- Protocol versions: TLS 1.3 only (`rustls::version::TLS13`).
- Cipher suites: the rustls defaults for TLS 1.3 (AES-GCM, ChaCha20-Poly1305).
- ALPN: `vnox-lnex/3`. A connection without the negotiated ALPN is dropped before any
- ALPN: `vnox-lnex/4`. A connection without the negotiated ALPN is dropped before any
LNEx byte is read.
- No client certificates.
- Handshake timeouts: 15 seconds for the TLS handshake and 15 seconds for the LNEx HELLO/AUTH/SESSION exchange.
@ -99,7 +101,7 @@ The server peeks at the first byte of a new connection (up to 2 seconds).
A TLS client sends a handshake record (`0x16`) immediately. Anything else (a v2 client
waits for the server HELLO and sends nothing, a plaintext client sends LNEx bytes)
receives one plaintext LNEx `Error` frame, `ErrorCode::VersionMismatch`, with the message
`TLS 1.3 required (LNEx v3): update your client`, and the connection is closed. This
`TLS 1.3 required (LNEx v4): update your client`, and the connection is closed. This
frame is the only plaintext the gateway ever writes and it contains no secrets.
## Client
@ -150,7 +152,7 @@ TLS 1.3 handshake with a custom ServerCertVerifier:
UI on UntrustedServer: show host, fingerprint (grouped hex), "Trust" / "Cancel".
Trust -> trust_store[host:port] = { pin, fingerprint }, reconnect.
LNEx v3 handshake inside the tunnel (see below)
LNEx v4 handshake inside the tunnel (see below)
after a valid server HELLO:
rec.identity set and != server_pubkey -> ERROR IdentityChanged (hard block)
otherwise store identity (TOFU of the identity inside an already trusted channel)
@ -175,7 +177,7 @@ When a pinned server presents another SPKI the client:
server migration (for example moving from a self-signed certificate to Let's Encrypt
or restoring a server without its `server_identity.json`).
## LNEx v3 handshake inside TLS
## LNEx v4 handshake inside TLS
The 12 byte packet header and protobuf payloads are unchanged. Frames are written
directly into the TLS stream. The `flags` field must be `0` on the TCP control plane
@ -184,10 +186,10 @@ directly into the TLS stream. The `flags` field must be `0` on the TCP control p
```
Client Gateway
| -- TCP + TLS 1.3 handshake (ALPN) ---> |
| both sides: binding = Export("EXPORTER-VNOX-LNEx-v3-channel-binding", no context, 32)
| <------ HELLO (seq 0) ---------------- | lnex_version="v3", server_pubkey, challenge_nonce,
| both sides: binding = Export("EXPORTER-VNOX-LNEx-v4-channel-binding", no context, 32)
| <------ HELLO (seq 0) ---------------- | lnex_version="v4", server_pubkey, challenge_nonce,
| | node_name, private_mode, server_signature
| ------- AUTH (seq 0) ----------------> | client_pubkey, nickname, lnex_version="v3", signature
| ------- AUTH (seq 0) ----------------> | client_pubkey, nickname, lnex_version="v4", signature, account_proof
| <------ SESSION (seq 1) -------------- | session_id, token, expires_at
```
@ -195,10 +197,10 @@ Signatures (Ed25519, strict verification):
```
server_signature = Sign(server_key,
"VNOX-LNEx-v3-server-hello\0" || binding || protobuf(Hello with server_signature empty))
"VNOX-LNEx-v4-server-hello\0" || binding || protobuf(Hello with server_signature empty))
client signature = Sign(client_key,
"VNOX-LNEx-v3-client-auth\0" || binding
"VNOX-LNEx-v4-client-auth\0" || binding
|| u32be(len(signed_hello)) || signed_hello
|| protobuf(Auth with signature empty))
```
@ -238,18 +240,18 @@ needs the client to trust the gateway certificate (`--trust-first-use` or `--fin
| Client | Server | Result |
|--------|--------|--------|
| v3 | v3 | works |
| v2 (old) | v3 | server sends a plaintext `Error(VersionMismatch)` "TLS 1.3 required (LNEx v3): update your client"; an old client shows a handshake error or times out. Nothing is negotiated. |
| v3 | v2 (old) | the server answers the TLS ClientHello with LNEx bytes. The client maps the rustls decode failure to "The server does not speak TLS 1.3 (LNEx v3). It is probably an outdated server, ask the owner to update." No retry in plaintext. |
| v3, TLS 1.2 only peer | v3 | handshake failure, protocol version alert, same explicit message. |
| v3 | v3 with `lnex_version` other than `v3` in HELLO/AUTH | `VersionMismatch`, connection closed. |
| v4 | v4 | works |
| v2 (old) | v4 | server sends a plaintext `Error(VersionMismatch)` "TLS 1.3 required (LNEx v4): update your client"; an old client shows a handshake error or times out. Nothing is negotiated. |
| v4 | v2 (old) | the server answers the TLS ClientHello with LNEx bytes. The client maps the rustls decode failure to "The server does not speak TLS 1.3 (LNEx v4). It is probably an outdated server, ask the owner to update." No retry in plaintext. |
| v4, TLS 1.2 only peer | v4 | handshake failure, protocol version alert, same explicit message. |
| v4 | v4 with `lnex_version` other than `v4` in HELLO/AUTH | `VersionMismatch`, connection closed. |
There is no version negotiation and no compatibility window: the old handshake is not
implemented in the new binaries.
## Operations: enabling it on a server
1. Update the gateway (and `serverd`) to the LNEx v3 build. Remove `tls_enabled = false`
1. Update the gateway (and `serverd`) to the LNEx v4 build. Remove `tls_enabled = false`
if present.
2. Self-signed: nothing to configure. Start the gateway, read the fingerprint from the
log or `data_dir/tls/fingerprint.txt`, publish it to your users.