VTX 1 · core · beta draft d03
VTX 1 Wire Specification: core
§5Connection establishment and capability negotiation
A session is ready one round trip after the secure transport is up, or two when the user signs in with a passkey or token.
Diagram: VTX handshake · discovery and TLS, then HELLO to READY. Drawn in the PDF version,
01-vtx-1-wire-specification-core.pdf.
Without sign-in, WELCOME and READY leave the server back to back, and the client renders after a single round trip.
- Discovery. The client parses the URI (below). For
vtx://host/appit queries SVCB at_vtx.host; forvtx://host:port/appit queries_port._vtx.host(Port Prefix Naming, RFC 9460 §2.3). Records withoutalpnare skipped. Without SVCB, the client tries SRV at_vtx._udp.hostand_vtx._tcp.host, then A/AAAA on the default port, 22100 (Section 16). A host given as an IP literal skips DNS discovery. - Connection racing. When both
vtxq1andvtx1are on offer, the client races them as Happy Eyeballs does (RFC 8305): QUIC first, TCP 250 ms later. The first handshake to complete wins. - Secure transport. TLS 1.3, an SSH session, or a Noise handshake (Section 2), with server authentication as below.
- HELLO (client): versions, capabilities, limits and display.
- WELCOME (server): the chosen version, the accepted capabilities and, if the user must sign in, the auth methods. A WebAuthn challenge and an OIDC nonce seed ride in WELCOME, so the client can answer at once.
- AUTH (client), only when WELCOME lists methods. A failure returns AUTH_FAILED.
- READY (server): session ID, resume token, scene state,
input_seqand, optionally, the signed-in user. Channels 1, 2 and 4 are now open, and channels 3 and 5 when their capabilities were accepted.
When no sign-in is needed, the server sends WELCOME and READY back to back. The client renders every credential prompt in its trusted zone (Section 12), never in scene content.
URI. vtx-URI = "vtx://" host [ ":" port ] path-abempty [ "?" query ] [ "#" fragment ], with the rules of RFC 3986; userinfo is not allowed. HELLO's target is the path and query exactly as written, percent-encoding kept, starting with / (an empty path becomes /). The fragment never leaves the client. Browser clients append the target to /.well-known/vtx (Section 2).
Server authentication. The client authenticates the origin host, which is the host in the URI, and never an SVCB or SRV target name; TLS SNI carries the origin host.
- DANE. When the TLSA RRset at
_port._udp.target(QUIC) or_port._tcp.target(TCP) for the selected SVCB or SRV target is DNSSEC-secure, the client uses it as RFC 7671 describes, accepting the usages DANE-EE (3) and DANE-TA (2). The client validates DNSSEC itself, or relies on a validating resolver it reaches over an authenticated channel. - A secure TLSA RRset that matches no certificate is fatal, and so is a bogus DNSSEC answer.
- With no TLSA records, or an insecure answer, the client validates the certificate for the origin host against WebPKI.
- The trusted zone shows "DANE" only after a TLSA match.
Handshake states and timeouts.
- Before WELCOME, the client sends only HELLO. Between WELCOME and READY, the only other frames allowed are AUTH, AUTH_CHALLENGE, AUTH_FAILED, PING, PONG and CLOSE; anything else is
protocol_error. - The server closes with
protocol_errorwhen no HELLO arrives within 10 seconds of the secure transport, and withauth_failedwhen sign-in has not completed 120 seconds after WELCOME, or after 5 failed attempts. - After AUTH_FAILED with
retry: true, the client may try any offered method. Awebauthnretry uses a fresh challenge, which the server sends in AUTH_CHALLENGE; AUTH_CHALLENGE also serves methods with more than one step that are registered later.
Control frames (channel 0)
| Type | Name | Direction | Payload |
|---|---|---|---|
| 0x10 | HELLO | C→S | Offer: versions, profile, caps, limits, display, locale, unicode, target, resume, client |
| 0x11 | WELCOME | S→C | version, unicode, accepted caps, server limits, server, auth offers, linger, idle |
| 0x12 | AUTH | C→S | method plus its credential |
| 0x13 | AUTH_CHALLENGE | S→C | method plus its next challenge |
| 0x14 | AUTH_FAILED | S→C | reason (credential, expired, revoked, unsupported or locked), message, whether retry is allowed |
| 0x15 | READY | S→C | session, token, state, resumed, input_seq, linger, user |
| 0x16 | OPEN | Both | channel, type, params |
| 0x17 | OPEN_OK | Both | channel, params |
| 0x18 | OPEN_REFUSED | Both | channel, code, reason |
| 0x19 | CAPS | Both | Client: a new full offer, optionally with new limits, locale and tz. Server: the full accepted set, answer: true and the scene state it applies from |
| 0x1A | DISPLAY | C→S | New display metrics (resize, scale, dark mode, colours) |
| 0x1B | PING | Both | nonce |
| 0x1C | PONG | Both | The nonce echoed |
| 0x1D | TOKEN | S→C | A fresh resume token |
| 0x1E | DETACH | C→S | Keep the session; this connection is ending |
| 0x1F | GOAWAY | S→C | code, reason, optional reconnect URI |
| 0x20 | SESSIONS | C→S | Empty; asks for the signed-in user's sessions, after READY |
| 0x21 | SESSION_LIST | S→C | sessions, each with session, app, title, attached |
HELLO fields
| Field | Type | Meaning |
|---|---|---|
versions |
array of uint | Supported major versions; this spec is 1. Draft builds are told apart by their beta identifiers (Section 16), not here |
profile |
0–3 | Rendering profile, as a hint only; capabilities govern |
caps |
map | Offered capabilities (below) |
limits |
map | max_frame, window, glyph_slots, cache_bytes, scene_nodes, retain, max_update, max_clip (Section 14) |
display |
map | cols, rows, colors; optional px, cell_px, scale, dark, contrast, reduced_motion, and the colours fg, bg and palette (16 entries) that the VT engine reports to colour queries (Section 8) |
locale |
text | BCP 47 language tag |
tz |
text, optional | IANA time zone name, such as Europe/Amsterdam; datetime components use it (Section 9) |
unicode |
text | Unicode version for grapheme and width rules, e.g. 15.1 |
target |
text, optional | Application path and query from the URI |
resume |
map, optional | session and state, plus token when this device holds it; without a token, the user signs in as the session's owner (Section 6) |
client |
map, optional | name, version, platform |
inputs |
array of device descriptors, optional | The client's input devices (Section 11); a client may leave this out and send DEVICES after READY |
HELLO MUST fit in 4,096 bytes; a client with many input devices may leave inputs out and send DEVICES after READY. WELCOME's unicode field states the version both sides then use: the lower of the client's and the server's, compared as major.minor numbers.
Capability negotiation
- The server's accepted set is a subset of the client's offer. Neither side may use a capability outside it.
- Unknown capability keys are ignored. Extension keys carry a domain, like
telemetry@example.com. - A value is
trueor a parameter, such as a list. The server answers with the parameter it chose. - Only the client offers changes mid-session: CAPS with its full new offer, optionally with new
limits,localeandtz, for example after it moves to a larger screen or the user changes language. The server answers with CAPS holding the full accepted set,answer: trueand the scene state from which the new set applies. Before that state, the server removes or replaces nodes that depend on a dropped capability; until then the client renders their fallback. - New limits, locale and time zone apply from that same state. Until then, the old limits hold, and the server must not exceed either the old or the new ones. The application hears of the change as a session event (Section 17).
| Key | Value | Meaning |
|---|---|---|
cells |
true | Layer 1 grids (Section 8) |
glyph.bitmap1 |
true | 1-bit bitmap glyphs |
glyph.bitmap8 |
true | 8-bit coverage glyphs |
glyph.path |
true | Vector path glyphs |
font |
array of media types | Font resources: font/woff2, font/otf, font/ttf |
components |
array of catalog URIs | Layer 2 with these catalogs (Section 9) |
input.keys |
true | Distinct press, repeat and release key events |
input.ime |
true | Composition events |
input.pointer |
true | Pointer and wheel events |
input.touch |
true | Touch contacts |
clipboard |
array of media types | Clipboard channel; text/plain;charset=utf-8 is required in the list |
zone.uv |
true | User-verified approvals, with WebAuthn or a smart card (Section 12) |
auth |
array of methods | Auth methods the client can perform |
input.pen |
true |
Pen pressure, tilt, twist and hover |
input.lock |
true |
Pointer lock with relative motion |
input.gestures |
array of gesture names | Gestures the client can recognise |
input.gamepad |
true |
Gamepads and joysticks |
input.dictation |
true |
Dictation from voice devices |
input.a11y |
true |
Accessibility actions |
haptics |
array of effects | Haptic effects the client can drive |
The extensions' keys are listed in ext/registry.json of the definitions bundle, each with its extension, and none repeats a key of the core. Keys that share a prefix form a family: surface. for surface kinds (surface.vector, surface.image, surface.grid, surface.pixel, surface.a11y, surface.window), audio. and video. for capture and clips, input. for input options (input.keylock, input.datagrams) and redirect. for what the device shares into a session (redirect.drives, redirect.printers, redirect.media, redirect.smartcards, redirect.usb). The others are cells.sub, theme, composites, audio, video, transfer, exec, forward, notify, device, viewers, sensors, displays, broker and wasm, and drafts during the beta.
Auth methods
| Method | Flow |
|---|---|
tls-cert |
The client certificate already verified in TLS; AUTH carries no credential. Suited to devices: the certificate is requested during the TLS handshake, before the user has chosen how to sign in, and does not pass through load balancers that end TLS. People with smart cards use x509 |
ssh |
The SSH-authenticated user; SSH binding only |
webauthn |
WELCOME carries a challenge of at least 16 random bytes; AUTH returns the passkey assertion (parameters below) |
oidc |
WELCOME names issuer, client_id and a 32-byte nonce_seed; the client signs in with authorization code and PKCE in the system browser, with the OIDC nonce derived from the seed and the server's host name (below), then sends the ID token. The server checks issuer, audience, azp, expiry and the nonce, so a token minted for one server cannot be relayed to another |
token |
A pre-provisioned bearer token for devices without a user, such as kiosks and IoT; sent only to the host it was provisioned for |
x509 |
WELCOME carries a challenge; the client signs it with a certificate's private key, usually on a smart card, and AUTH returns the signature and the certificate chain (parameters below) |
OIDC nonce and redirect. The nonce is base64url(SHA-256("vtx1-oidc" ‖ host ‖ nonce_seed)) without padding, where host is the origin host the client authenticated, in lower-case ASCII (A-labels for internationalized names), and nonce_seed is the 32 bytes from WELCOME. This works the same over every binding, including browsers, which cannot reach a TLS exporter. Native clients use a loopback redirect, http://127.0.0.1:{port}/vtx/oidc with a port chosen per sign-in (RFC 8252 §7.3); browser clients use /vtx/oidc on their own origin. The provider must register these redirects for the client_id. Section 19 gives a test vector.
WebAuthn parameters.
- The rpId is the host name from the
vtxURI, which the client has authenticated through TLS or SSH. Clients MUST NOT assert for any other rpId. typeiswebauthn.get. For sign-in the challenge is WELCOME's as given; for approvals it is defined in Section 12.allowCredentialsis empty, so discoverable passkeys are used.userVerificationispreferredfor sign-in andrequiredfor approvals.- Servers verify the rpId hash, the challenge and the signature. They accept the origin
https://plus the rpId, every origin they list in/.well-known/webauthn, and the app origins of the native clients they accept. - Clients on another origin. Browsers and native apps may use a passkey only for their own domain, or for a domain that vouches for them. A server that accepts browser clients from another origin, such as a web client on
app.example.netfor a server onvtx.example.net, MUST publish/.well-known/webauthnon its HTTPS host (WebAuthn related origin requests), listing those origins, for example{"origins": ["https://app.example.net"]}. It SHOULD publish/.well-known/apple-app-site-association(underwebcredentials) and/.well-known/assetlinks.jsonfor the native clients it accepts. The list is each server's own configuration, so no server depends on another domain. - The rpId stays the host from the URI in every case: that binding keeps one server from passing off another server's sign-in as its own.
- A client that cannot use a passkey for the host, such as a browser without related-origin support or an app the host does not list, does not offer
webauthn, and signs in with another method such asoidcortoken. Approvals signed with a passkey (Section 12) follow the same rule.
x509 parameters. x509 signs in with a certificate whose private key the client holds, usually on a smart card such as a PIV card, a national eID card or the Dutch UZI-pas, reached through PKCS#11, Windows CNG or macOS CryptoTokenKit.
- WELCOME's offer carries a 32-byte random
challenge. It may list incasthe SHA-256 of the SubjectPublicKeyInfo of each CA the server accepts, so the client offers only certificates that chain to one of them. - The client signs the bytes
"vtx1-x509" ‖ host ‖ challenge, withhostas for the OIDC nonce. AUTH carriesx509:certs(DER, end-entity first, then intermediates),algandsig, plus an optional stapled OCSP response inocsp. algis a COSE algorithm: ES256 (−7), ES384 (−35), ES512 (−36), EdDSA (−8), PS256 (−37), PS384 (−38) or RS256 (−257). ECDSA signatures are encoded as r ‖ s (RFC 9053 §2.1).- The server validates the chain to a configured trust anchor (RFC 5280), requires the digitalSignature key usage, checks revocation by OCSP or CRL, verifies the signature and maps the certificate to a user. A revoked certificate fails with reason
revoked, an expired one withexpired. - The PIN unlocks the card on the client. It is entered in the trusted zone, on the reader's own PIN pad or in the operating system's dialog, and never leaves the client.
- With
removal: "detach"in the offer, the client clears the scene from the screen and sends DETACH when the card is removed; putting the card back resumes the session with a fresh sign-in (Section 6). The default isnone. - Web pages cannot reach a card's key, so browser clients offer
x509only through an extension or a native helper. They can still use a card throughtls-cert.
Section 19 gives a test vector.
Sign-in UI. While the user signs in, the trusted zone shows the server identity and, for oidc, the issuer; for x509, the certificate's subject and issuer.