vtx.foundation draft d03

VTX 1 · extension · draft d01

VTX Brokering 1: app lists, launching and session routing

Nov 15, 20268 pagesprofile 1draft d01draftMIT licence

§1Status and scope

Brokering 1 gives a user one address for everything they may run. The broker lists the published desktops and applications, starts the one the user picks on a session host it chooses, and hands the client over to that host with a one-time ticket. Later, it finds the user's sessions wherever they run, so reconnecting never depends on remembering a host. It is an extension of VTX 1, draft d01, in conformance profile 1.

The broker is an ordinary VTX server that the user signs in to. The session hosts are VTX servers too. Seamless applications open as Windows 1 windows, on any display of Displays 1.

Adds What it is
broker A capability: the client can list and launch; the server is a broker
broker channel One channel the client opens on its broker connection: the catalog, launching, the user's sessions, reconnecting and signing out
ticket A sign-in method: the client signs in to a session host with the ticket the broker gave it
launch An application event: a session host's session manager is told to start an item

This is the part of a remote desktop farm that RDS calls the connection broker and the RemoteApp and Desktop Connections feed, and that Citrix calls StoreFront and the Delivery Controller.

Out of scope. How a broker and its hosts talk among themselves: registering hosts, reporting load and redeeming tickets go over the farm's own interface; Section 10 says only what a redemption must return. Which host the broker picks. Licensing. Relaying VTX through a gateway at the edge of a network. User profiles that follow the user between hosts.

§2Capabilities and the broker channel

A client offers broker in HELLO; a server that grants it in WELCOME is a broker. After READY, the client opens one channel of type broker, and the server answers OPEN_OK with the catalog and the user's sessions.

cap-broker = {
  ? "files": bool,            ; client: it can open its own files with published items
}
Frame Direction What it carries
0x10 CATALOG Server to client Every desktop and application the user may run; again after every change
0x11 LAUNCH Client to server Start an item, optionally with files and a display
0x12 ROUTE Server to client Where to go: a host, a ticket and the host's key; or "it opened in a session you are attached to"
0x13 REFUSED Server to client Why a request failed
0x14 RUNNING Server to client The user's sessions across the farm; again after every change
0x15 RECONNECT Client to server Get back into a running session
0x16 SIGNOUT Client to server End a session

Only the client opens the channel (an odd ID), at most one per connection. LAUNCH, RECONNECT and SIGNOUT carry a request number that grows with each request; at most 8 may wait for an answer at once, and answers may come in any order.

Session hosts. A host does not need the broker capability. It offers the ticket sign-in method in WELCOME's auth list, and accepts only tickets from its own broker. One server can be both broker and host: then ROUTE simply names the same host.

§3The catalog

The catalog lists what this user may run, and nothing else. The broker sends it whole when the channel opens, and again whenever it changes: an application is published or withdrawn, or the user's groups change.

brk-catalog = {                                       ; 0x10 CATALOG, S->C: on open and after every change
  "version": uint,            ; grows with every change
  "items": [* catalog-item],
}
catalog-item = {
  "id": item-id,
  "name": tstr .size (1..80),
  "kind": "desktop" / "app",
  ? "icon": res-hash,         ; an image resource, fetched on the resource channel
  ? "folder": tstr,           ; up to three levels, e.g. "Office/Mail"
  ? "description": tstr .size (1..200),
  ? "collection": tstr .size (1..64),   ; items of one collection share a session on one host
  ? "types": [1*32 file-type],          ; the files an application opens
}
file-type = { "mime": tstr, ? "ext": [1*16 tstr] }

A small office farm might publish:

id name kind folder collection opens
office-desktop Office desktop desktop
evolution Mail app Office office .eml, .ics
writer Writer app Office office .odt, .docx
calc Calc app Office office .ods, .xlsx, .csv
gimp GIMP app Graphics graphics .png, .jpg

Collections. Applications of one collection run in one session on one host, as RemoteApp programs of one collection do. Mail, Writer and Calc above share a session: the second one the user starts opens in the session the first one started, so they can share the clipboard, files and memory. GIMP runs in a session of its own, possibly on a host with a GPU.

Icons. Icons are image resources, fetched and cached by their hash on v1's resource channel, so a catalog that is sent again costs no icon data.

Rules. Item ids are unique within a catalog. Desktops open no files, so they have no types. version grows with every CATALOG the broker sends.

§4At a glance

Diagram: launching an application · client, broker and session host. Drawn in the PDF version, 12-brokering-1.pdf.

The user signs in once, at the broker. The ticket goes from the broker to the client, from the client to the host, and back to the broker to be redeemed, so the host learns who the user is without a second sign-in. The pin tells the client which host to trust, so it never has to decide on a host's key by itself.

§5Launching

The client asks for an item; the broker decides where it runs and answers with one ROUTE or one REFUSED. What the broker decides depends on what the user already runs:

The user already has The broker ROUTE
Nothing of this item's collection Picks a host and prepares a new session there uri, ticket, pin, expires
A session of the collection, with this client attached Asks the host to start the item in that session session and joined: the new windows arrive on the connection the client already has
A session of the collection, with nobody attached Asks the host to start the item in that session uri, ticket, pin, expires and session: the client resumes it

In CBOR diagnostic notation, a launch and its hand-over:

LAUNCH {"req": 1, "item": "evolution"}
ROUTE  {"req": 1, "uri": "vtx://h12.farm.example.net/office", "ticket": h'5c0e…', "pin": h'a41f…', "expires": 60}

The hand-over. The client connects to the URI as to any VTX server, with one difference: it refuses the host unless the host presents the key whose SHA-256 is pin. HELLO carries the URI's target, and resume with the session and no token when ROUTE named one. The host offers ticket among its sign-in methods, and the client answers with it:

AUTH {"method": "ticket", "ticket": h'5c0e…'}

The host redeems the ticket with its broker, learns who the user is and what to start, and sends READY. A ticket works once, at that host, for expires seconds after ROUTE (at most 300). A ticket that is unknown, used or expired gets AUTH_FAILED with reason ticket; the client then asks the broker again.

Refusals.

code Meaning
unknown No such item in the user's catalog, or no such session
denied The user may not do this, such as opening a farm path outside their own storage
busy No host has room right now; the client may try again later
unavailable The item's hosts are down or being serviced
limit The user runs as many sessions as the farm allows
file The item does not open a file of that type

§6Sessions

RUNNING lists the user's sessions on every host of the farm, where v1's SESSION_LIST lists them on one server. The broker sends it when the channel opens and after every change: a session starts or ends, an item starts in it, or a connection attaches or detaches.

RUNNING {"sessions": [
  {"session": h'3b9d…', "host": "h12.farm.example.net", "items": ["evolution", "writer"], "attached": true},
  {"session": h'c071…', "host": "g3.farm.example.net", "items": ["gimp"], "attached": false}]}
The user wants to The client
Leave a session running Sends v1's DETACH on that host's connection; nothing changes at the broker except attached
Come back on the same device Resumes directly at the host with v1's resume token; the broker is not needed
Come back on another device Sends RECONNECT; the broker answers with a ROUTE that names the session, and the client resumes it with the ticket. A connection still attached elsewhere gets v1's GOAWAY taken_over
End a session Sends SIGNOUT; the host ends the session as a desktop signs out, and the next RUNNING no longer lists it

A SIGNOUT that fails is answered with REFUSED; one that succeeds has no answer of its own but that RUNNING. A connection attached to the session when it ends gets v1's GOAWAY session_ended.

§7Opening files

A user who double-clicks invoice.docx on the device should see it open in the published Writer. The client finds the item whose types cover the file and sends LAUNCH with it:

LAUNCH {"req": 4, "item": "writer", "files": [{"name": "invoice.docx", "size": 48213,
        "mime": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"}]}

Files from the device. Once the client is connected to the host (or at once, when ROUTE says joined), it uploads the files with Transfer 1, several as one set. Opening a file with an application is the user's own choice of that file, so the upload counts as a pick, as Transfer 1 requires. The host's session manager matches the upload with the launch by names and sizes, and opens the files in the item it started.

Files on the farm. A file already in the user's own storage on the farm goes by path, and nothing is uploaded. The broker refuses a path outside that storage with denied.

Rules. Only a client that offered files sends device files. Files go only to an application whose types cover each of them, by MIME type or extension; anything else is refused with file. At most 16 files per launch.

The host works on a copy of a device file. Saving it back to the device takes a download through the trusted zone (Transfer 1). Drive redirection, which lets a remote application write to the device's own file, is Drives 1.

§8On the device

A client may place the catalog among the device's own applications, so a published Writer starts from the Start menu, Launchpad or an application launcher like a local one. This is the device's business, not the wire's, but every client should do it the same way:

  • Only when the user agrees, once per broker, as RDS asks before adding a RemoteApp feed to the Start menu.
  • Marked as remote. Entries sit in a folder named after the broker, and their names say which broker they come from, such as "Writer (apps.farm.example.net)", so a remote application is never mistaken for a local one.
  • Kept current. When CATALOG's version changes, the client adds, renames and removes entries to match, and fetches new icons by their hash.
  • File associations as "Open with". The client offers published applications for the file types in their types. It never makes one the default handler without the user's say, and the device's own prompt for that stays in place.

Launch links. An entry stores the broker's URI with the item in the fragment: vtx://apps.farm.example.net/#launch=writer. The fragment never leaves the client (v1), so the broker sees an ordinary connection; the client connects, opens the broker channel and sends LAUNCH for writer. The same link works anywhere a vtx:// link does.

§9With other extensions, and without the capability

Extension With brokering
Windows 1 Seamless items open as windows on the host connection. Windows from several hosts sit side by side, each with its own host beside the title
Displays 1 LAUNCH's display reaches the host, which names it on the item's first window. A desktop item covers the displays in the layout's use
Transfer 1 Device files opened with an item travel as an upload that counts as a pick (Section 7)
Devices 1 A device key signs the client in to the broker without a passkey prompt. Hosts need no device keys: the ticket signs the user in
Viewers 1 A brokered session is shared like any other: viewers join at the host, and need nothing from the broker

Without the capability. A v1 client can still use a farm. The broker shows its catalog as an ordinary VTX application, and a click ends the connection with GOAWAY carrying the host's URI in reconnect. The client follows it and signs in at the host again, since v1 sends no token to another host, and trusts the host by WebPKI, DANE or its key on first use. What it misses is the single sign-in, the vouched key, RUNNING and files.

§10Application interface

On a session host, a brokered target such as /office runs a session manager: the application that starts the published programs and lets the compositor show their windows. Each time an item must start in its session, after a redeemed ticket or a join, it gets a launch event:

{"kind":"launch","item":"evolution"}
{"kind":"launch","item":"writer","files":[{"name":"invoice.docx","size":48213,"mime":"application/vnd.openxmlformats-officedocument.wordprocessingml.document"}]}
{"kind":"launch","item":"calc","files":[{"path":"Documents/budget-2027.ods"}],"display":"d2"}

The session manager maps the item to a program through the farm's own configuration and starts it; the compositor then writes the program's windows as Windows 1 ops. Device files arrive as a Transfer 1 upload, which the session manager matches by names and sizes and opens in the program. A farm path is opened where it lies. When display is present, the first window names that display.

Redeeming a ticket. Between host and broker, the farm's own interface carries the redemption. This specification fixes only what it must do and return, so that brokers and hosts from different makers can work together:

The host sends The broker returns
The ticket The user who signs in
Its own key The item to start, its files and display
The session to resume or join, if any

The broker answers only when the ticket is unused, unexpired and was given for the host whose key is sent, and marks it used before it answers. A host that cannot reach its broker refuses the sign-in with reason ticket.

§11Security

A broker signs the user in once and then sends them to machines the user never chose. The rules below keep that hand-over as safe as signing in to each host directly.

  • Tickets. 32 random bytes, used once, within expires seconds (at most 300), and only at the host they were minted for: at redemption the broker checks the key of the host that presents the ticket. Tickets travel only inside the encrypted broker and host connections. A stolen ticket is useless at any other host, and after its first use.
  • Vouched hosts. The client refuses a host whose key does not match pin, even when WebPKI would accept its certificate, so a hijacked DNS name cannot receive the user. For Noise hosts the pin replaces trust on first use. The trusted zone shows the host together with the broker that vouched for it, and Windows 1 still shows each window's host beside its title.
  • Resume tokens stay put. v1 sends a resume token only to the host that issued it, and Brokering 1 keeps that: a broker never sees one. Getting back in from another device goes through RECONNECT and a fresh ticket.
  • Only the user's own. The catalog lists only what the user may run, and RUNNING only the user's own sessions. A farm path outside the user's own storage is refused with denied.
  • Launch links. A link with #launch= can only start an item from the catalog of the broker it names, after the user signs in there. When such a link comes from outside the client, from a mail or a web page, the client names the broker and the item and asks once before it launches.
  • Limits. At most 8 requests waiting, 16 files per launch, 64 items per session in RUNNING, and tickets valid for at most 300 seconds.

§12Definitions and checks

The definitions live in the bundle under ext/brokering-1/, next to Displays 1:

File What it holds
vtx-brokering-1.cddl The capability, the broker channel and its seven frames, and the ticket sign-in
vtx-app-events-brokering-1.schema.json Server lines to an application, plus the launch event. Brokering 1 adds no scene op, so Displays 1's ops and application schemas apply
examples/valid/ Two catalogs, the launch trace (Mail on one host, Writer with a file joining it, GIMP on a second host, detach and sign-out), the reconnect trace (a second device, an expired ticket, a retry) and a session manager's lines
examples/invalid/ Broken catalogs, launch events and traces, each with the check that must catch it

tools/gen_ext_brokering.py writes the schema, built on the Displays 1 generator; tools/make_brokering.py writes the examples, in the multi-connection trace format of Devices 1. Both are deterministic.

The validator's Section 20 runs 55 checks, and every one passes:

Part Checks What they cover
Setup 6 The schema is valid; the CDDL parses alone and with the first nine extensions, Windows 1 and Displays 1; no rule is defined twice; earlier schemas reject launch; the core alone rejects the ticket sign-in
CDDL and catalogs 21 7 valid samples accepted and 9 malformed ones rejected; 2 catalogs pass the CDDL and the rules of Section 3; 3 broken catalogs pass the CDDL and fail a rule
Traces 22 2 valid traces replayed in full across the broker and the hosts; 20 broken ones, each caught by the right check, among them a reused ticket, a ticket taken to the wrong host, a host that does not match its pin, an expired ticket accepted, a file the item does not open, a join to a session the client is not in, and a signed-out session still running
Application interface 6 4 valid lines, each launch naming a catalog item and only files it opens; 2 rejected

The whole bundle runs 2,543 checks, all passing.

§13Wire summary

Everything Brokering 1 adds, for the registry and for implementers:

Kind Addition
Capability broker: the client sends {} or {"files": true}; a server that grants it is a broker
Channel type broker, opened by the client, at most one per connection: 0x10 CATALOG, 0x11 LAUNCH, 0x12 ROUTE, 0x13 REFUSED, 0x14 RUNNING, 0x15 RECONNECT, 0x16 SIGNOUT
Sign-in method ticket, with AUTH's ticket (32 bytes); AUTH_FAILED reason ticket
Refusal codes unknown, denied, busy, unavailable, limit, file
Application event {"kind":"launch","item":…,"files":[…],"display":…}, to a session host's session manager
Launch link vtx://broker/#launch=<item>, read only by the client

No frame of the core, the first nine extensions, Windows 1 or Displays 1 changes meaning. A host still accepts every sign-in method it did before, and a client without Brokering 1 still reaches a farm through GOAWAY's reconnect (Section 9).