Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

5.9 KB
Raw Blame

Private WebSocket login credentials

Private chat, builder chat, builder preview, progress and streaming speech WebSockets no longer accept token or access_token in the query string, including empty, repeated and percent-encoded names. There is no query-credential fallback.

Browser clients offer two subprotocol values:

new WebSocket(urlWithoutCredentials, [
  "xagent-auth-v1",
  `xagent-auth-token.${accessToken}`,
]);

Non-browser clients may instead send one Authorization: Bearer ... header. Other Authorization schemes (such as gateway Basic authentication) and empty headers are not application login credentials. They do not authenticate a user or conflict with the browser carrier; malformed Bearer credentials are rejected. Combining the two carriers or supplying duplicate/malformed login credentials is rejected. The server does not select or echo the credential subprotocol. This is a header carrier for the existing access JWT, not a newly minted, short-lived or single-use ticket. Use WSS in production and treat the entire Sec-WebSocket-Protocol request header as sensitive in proxy/APM/debug logs. The common application text redactor recognizes the new credential prefix, WebSocket URLs and navigation tickets; it cannot sanitize third-party logs or delete credentials already retained in historical logs.

Existing user/purpose/signature/session-generation checks, task ownership, five-second idle revocation polling and chat-message revalidation still apply. Streaming speech revalidates before starting the provider session and uses the same revocation monitor. Individual PCM fragments and commit/close controls do not perform database reads; revocation during an active stream is detected by that monitor. Changing an explicit token prop changes the hook's in-memory login identity, so uploads and retries are not reused across explicit login identities. An auth-context refresh for the same user/session intentionally retains that identity while using the refreshed credential for subsequent connections.

The SaaS external client/session protocols retain their separate, purpose-scoped admission contracts and are not granted access by this helper.

Public widget/share guest tokens

Public widget and share chat sockets (/api/widget/chat/ws/{task_id}, /api/share/chat/ws/{task_id}) use the same header carriers for the 30-day guest token: the xagent-auth-v1 + xagent-auth-token.<token> subprotocol pair from browsers, or Authorization: Bearer from other clients. The old ?token= query parameter is retired: a handshake that still carries a URI credential is refused even next to a valid header (accepted, then closed with 4003 "Authentication required"). The guest token remains a guest capability, not a user login: admission, per-guest task isolation and per-message revalidation are unchanged, and the server negotiates only xagent-auth-v1.

Public file routes (/api/files/public/preview|download/{file_id}) likewise read the guest token only from the Authorization header and ignore ?token=. URLs the browser loads itself (media elements, "Open" links, HTML-preview assets) cannot send that header, so the frontend exchanges it for a short-lived ticket bound to one file: POST /api/files/public/tickets/{file_id} returns {ticket, expires_in}, used as ?ticket= on those two routes (including relative_path assets under that file). The ticket lives XAGENT_FILE_STREAM_TICKET_TTL_SECONDS and is signed but readable, so it carries no reusable identity: only a digest of the share token / widget key and a keyed, non-reversible binding of the guest id (never the id itself, which /api/widget/auth would re-sign into a fresh guest token). Redemption restores the guest from the file's own task and revalidates against the live deployment on every use, so disabling or rotating the link revokes it. One exception: a ticket minted from a legacy widget token that carries no widget_key has no key digest to compare, so rotating the widget key does not revoke it before it expires; disabling or unpublishing the widget still does, as does key rotation for share-link and keyed widget tickets. A ticket is not accepted as a Bearer guest token, and a guest token or private stream ticket is not accepted as ?ticket=. Server access and handshake logs redact credential-like query values (token, ticket, *_key, ...), and the per-header lines the WebSocket stack logs at debug level (--debug) mask the xagent-auth-token. subprotocol item, Authorization/Proxy-Authorization credentials (the scheme is kept), cookies and *-key/*-token headers.

Deployment

Deploy matching frontend and every API replica together. Old private query-JWT clients must migrate; old API replicas do not understand browser header login. For the public guest contract, roll out the API first (it accepts the header carriers and serves the ticket endpoint), then the frontend and any embedded widget bundle. A new frontend against an old API replica cannot mint file tickets (404, so media falls back to a blob fetch and guest-task "Open" links and HTML-preview assets fail) and its header-only guest sockets are refused; an old frontend against the new API loses guest-task file and socket access because its ?token= URLs are ignored. Legacy URI credentials are rejected before the upgrade. In production this is an HTTP 403 failed handshake (typically browser close 1006), not a delivered WebSocket close reason. There is no authenticated legacy fallback. Proxies must forward Sec-WebSocket-Protocol unchanged on upgrade requests.

Integrations with additional authentication middleware must inspect the offered login credential for initial MFA admission, per-frame checks and idle revocation. The core upgrade, SaaS authentication adapters and MFA changes require combined release acceptance.

This addresses the private and public guest WebSocket URL carriers and the public file-route guest token, not historical-log cleanup, one-use capabilities or OAuth navigation.