vtx.foundation draft d03

VTX 1 · core · beta draft d03

VTX 1 Wire Specification: core

Oct 11, 2026, revised Nov 16, 202639 pagesALPN vtx1-d03MIT licence

§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.

  1. Discovery. The client parses the URI (below). For vtx://host/app it queries SVCB at _vtx.host; for vtx://host:port/app it queries _port._vtx.host (Port Prefix Naming, RFC 9460 §2.3). Records without alpn are skipped. Without SVCB, the client tries SRV at _vtx._udp.host and _vtx._tcp.host, then A/AAAA on the default port, 22100 (Section 16). A host given as an IP literal skips DNS discovery.
  2. Connection racing. When both vtxq1 and vtx1 are on offer, the client races them as Happy Eyeballs does (RFC 8305): QUIC first, TCP 250 ms later. The first handshake to complete wins.
  3. Secure transport. TLS 1.3, an SSH session, or a Noise handshake (Section 2), with server authentication as below.
  4. HELLO (client): versions, capabilities, limits and display.
  5. 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.
  6. AUTH (client), only when WELCOME lists methods. A failure returns AUTH_FAILED.
  7. READY (server): session ID, resume token, scene state, input_seq and, 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_error when no HELLO arrives within 10 seconds of the secure transport, and with auth_failed when 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. A webauthn retry 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 true or 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, locale and tz, 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: true and 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 vtx URI, which the client has authenticated through TLS or SSH. Clients MUST NOT assert for any other rpId.
  • type is webauthn.get. For sign-in the challenge is WELCOME's as given; for approvals it is defined in Section 12.
  • allowCredentials is empty, so discoverable passkeys are used. userVerification is preferred for sign-in and required for 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.net for a server on vtx.example.net, MUST publish /.well-known/webauthn on 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 (under webcredentials) and /.well-known/assetlinks.json for 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 as oidc or token. 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 in cas the 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, with host as for the OIDC nonce. AUTH carries x509: certs (DER, end-entity first, then intermediates), alg and sig, plus an optional stapled OCSP response in ocsp.
  • alg is 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 with expired.
  • 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 is none.
  • Web pages cannot reach a card's key, so browser clients offer x509 only through an extension or a native helper. They can still use a card through tls-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.