VTX 1 · core · beta draft d03
VTX 1 Wire Specification: core
§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
tokensign-in or a resume it takes READY'suser, 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
requesteris{ name, kind }withkindagent,apporuser.riskislow,mediumorhigh.expiresis in seconds.- The client shows every field the digest covers: title, requester, risk, server identity, and both
detailandcommandwhen 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. decisionisallow,deny,expiredorunsupported.digestis 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 inproofit can give (defaultwebauthn). 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 returnsassertion:credential_id,authenticator_data,client_data_json,signature.x509: a smart-card signature over those bytes, returned inx509with the fields of anx509sign-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.uvor without a passkey or card for the signed-in user, answersunsupported.
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.