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

§12Trusted zone

Every client MUST reserve a trusted zone: UI that only the client draws, that scene content can never draw into, overlap, theme or imitate. It is what makes a VTX approval worth more than a button in a web page.

Requirements

  • The zone always shows the server's identity (host and trust mode: WebPKI, DANE or pinned key), the connection state and the signed-in user. The client knows the user from its own sign-in; after token sign-in or a resume it takes READY's user, which it labels as reported by the server.
  • It is visually distinct and stays reachable through the reserved key combination (Section 11).
  • On very small displays the zone MAY be a mode the client switches into, provided no scene content renders while it is shown.
  • Credential prompts (Section 5), smart-card PIN entry, approvals and permission requests appear only in the zone, or in the operating system's own dialogs.

Where the guarantee holds. The trusted zone's guarantees hold only where the server does not supply the client's code: installed clients, browser extensions, and a web client served from an origin that is independent of the server, such as the reference web client (Section 2). A web client that a VTX server serves itself runs code that server controls, and can draw a fake zone. A WebAuthn assertion names its origin in clientDataJSON; when that origin is the server's own, the assertion proves only that the user's authenticator was used, not what the user was shown. Applications record the origin with each approval, and may refuse high-risk approvals from the server's own origin.

Zone frames (channel 4)

Type Name Direction Payload
0x10 APPROVAL S→C { id, title, ? detail, ? command, risk, requester, ? expires, ? uv, ? proof }
0x11 APPROVAL_RESULT C→S { id, decision, digest, ? assertion, ? x509 }
0x12 PERMISSION S→C { id, perm, ? detail, ? url }
0x13 PERMISSION_RESULT C→S { id, decision, ? scope }
0x14 CLAIM S→C { ? name, ? icon, ? color }
0x15 CANCEL S→C { id }: withdraws a pending request

Approvals

  • requester is { name, kind } with kind agent, app or user. risk is low, medium or high. expires is in seconds.
  • The client shows every field the digest covers: title, requester, risk, server identity, and both detail and command when present. Text is shown verbatim: no Markdown, control characters made visible, bidirectional text isolated.
  • For risk: "high" the client MUST require a deliberate act: no default button, and Enter alone does not answer.
  • decision is allow, deny, expired or unsupported.
  • digest is the SHA-256 of the APPROVAL payload bytes exactly as received. The server MUST check it, which binds the answer to the request the user actually saw. Approval IDs MUST be unique within a session, and a server accepts one answer per ID.
  • With uv: true, the client proves that the user approved, using the first proof in proof it can give (default webauthn). Either proof covers the bytes "vtx1-approval" ‖ session ID ‖ digest, with the 16-byte session ID, which ties it to this session and this request. The application can store it as verifiable proof that this user approved exactly this request.
  • webauthn: a WebAuthn assertion with the Section 5 parameters and user verification required, whose challenge is the SHA-256 of those bytes. The client returns assertion: credential_id, authenticator_data, client_data_json, signature.
  • x509: a smart-card signature over those bytes, returned in x509 with the fields of an x509 sign-in (Section 5). The server checks the certificate as at sign-in, and it must map to the signed-in user. Cards usually hold a separate signing key that asks for the PIN on every use; that is the key to use.
  • A client that can give none of the listed proofs, for example without zone.uv or without a passkey or card for the signed-in user, answers unsupported.

Limits. At most 8 zone and clipboard requests may be pending in a session. The server must not send a ninth; a client that receives one closes the connection with policy_violation. A client may deny a permission request at once when the user denied the same permission earlier in the session.

Permissions in the core: clipboard.read, clipboard.write (writes outside a user activation, Section 13), open_url and pointer.lock (Section 11). For open_url the zone shows the full URL, and only https, http and mailto URLs are allowed. decision is allow or deny; scope is once, session or always. Grants with scope always are stored per server identity, and the user can revoke them in the client. The extensions add microphone, camera, screen and keyboard.lock (Media 1), clipboard.files (Transfer 1), recording (Viewers 1), motion, location, location.precise and environment (Sensors 1), fullscreen (Windows 1), drives (Drives 1), printers (Printers 1) and smartcards (Smart Cards 1).

Claimed identity. CLAIM lets an agent present its name, an icon (a glyph resource, Section 10) and an accent colour as #rrggbb. The client shows it labelled as claimed by the server, visibly separate from the verified server identity, and ignores the icon if it lacks the glyph capability. This is where A2UI's agentDisplayName and iconUrl land.