feat(web-client): authorize browser sessions and add read-only TCP diagnostics

[yardbirds0]

This browser remote-control feature is usable in the desktop configurations tested so far, but it is still experimental and not fully polished. Broader compatibility, long-session reliability, and some interactions need more work. Community testing, review, and contributions are welcome so we can improve it together.

Summary

Adds the authorization, session lifecycle, transparent WebSocket gateway, audit integration, and read-only network diagnostics needed by the companion browser client. The feature is disabled by default. This replaces the previous incremental commits with one consolidated feature commit based on official main at 630cdba399608b93a8ae6667f78bff995fd2b23c.

Companion frontend: databk/rustdesk-console-web#351

Authorization and session lifecycle

Operation	Authorization
Read client configuration and accessible devices	web_client.connect
Create a desktop session	Current login, active account, explicit connect permission, and target scope
Create an independent file session	Owned active desktop grant plus web_client.file_transfer covering the target
Read live session network diagnostics	The caller's own active desktop grant and current authorization
Cancel a session	Its owner under the same login, or scoped devices.disconnect for another user's session
Read server network information	Existing servers.view

The system owner retains the existing owner bypass. Every ordinary user needs an explicitly assigned Web Client role permission, including for their own devices. Address-book visibility, device ownership, native ACLs, and devices.view do not implicitly grant it. Global and device-group scopes apply equally to device selection and manually entered IDs. Unknown, disabled, out-of-scope, or ambiguously registered IDs are rejected. Existing native /api/peers ACL behavior is preserved.

Grants bind the actor, login JTI, registered device UUID/ID, server configuration, and desktop/file purpose. Two independent single-use tickets expire after 60 seconds; pending grants expire after 120 seconds, and active grants are bounded by eight hours and the login/parent expiry. Limits are eight grants per account and 256 per process. Current account, login, role, and device state are revalidated every 15 seconds with bounded validation deadlines. Revocation, expiry, cancellation, restart, and parent termination invalidate tickets and close the associated channels. Delayed results cannot revive closed sessions.

Gateway and security boundaries

• Adds the exact /api/web-client/socket Upgrade route with an explicitly configured HTTPS Origin. Tickets travel in the first WS message, never URLs. Console JWTs are not sent to the Worker or native servers.
• Validates rendezvous and relay signaling against the granted target, configured public key, connection purpose, and server-issued relay UUID. Upstreams are fixed administrator configuration; advertised or client-supplied addresses cannot redirect the gateway.
• Applies authentication/handshake deadlines, socket/message/forwarding-buffer limits, strict protobuf parsing, and cleanup on shutdown. Once admitted, native encrypted traffic is forwarded without decrypting remote passwords or media.
• Adds no database table or migration and requires no hbbs/hbbr fork for browser control. Native password/remote approval and feature permissions remain required.

The file role governs the supported independent file-channel flow. A transparent gateway cannot inspect all operations hidden inside an encrypted desktop stream; strict file/clipboard restrictions still require remote native permissions. Console roles also do not automatically govern publicly reachable native TCP/WS access.

Audit integration

Reuses console_audits with session/parent/target identifiers and explicit evidence sources. Admission/denial, relay opening, cancellation, administrative termination, revocation, expiry, and closure are server observations. Remote-authentication and file-transfer start/completion/failure reports are marked browser-sourced; they are not independent proof of remote execution or a guarantee of complete delivery.

Audit data excludes passwords, derived credentials, JWT/JTI, tickets, clipboard/chat/file content, and keystrokes. File metadata is restricted to basename, size, and direction with strict schemas and rate/count limits. Admission fails closed if its required audit cannot be written. Termination closes resources before attempting audit persistence.

Existing server management and TCP information

Extends the existing server-management APIs rather than adding a new administration tab. Optional SERVER_MANAGEMENT_LOCAL=1 reuses the existing management core inside Console, allowing an explicitly configured four-container installation to retain real management without another agent container or host service. It requires enrolled/label-checked containers, native management endpoints, a private management token, and an explicitly mounted Docker socket. Existing permission guards and mutation audits remain in force. Docker access grants host-level administration capability and is an opt-in deployment choice.

The official Docker non-root entrypoint now preserves UID 1000 while selecting the mounted socket's group only in that explicit mode. Missing sockets fail startup. Default deployments keep UID/GID 1000 and the private updater-state boundary.

TCP reads require no socket mount or helper for local system configuration. Linux namespace configuration, Windows templates, and supported macOS observations carry the actual reading scope and explicit failure reasons. System configuration is kept separate from actual connection observations. Session diagnostics independently report the final entry sender and hbbr relay sender; proxy/NAT/namespace/permission limitations return Unable to identify, without substituting a system default. No sysctl writes, module loading, algorithm selector, saved network preference, or additional network deployment remains.

Deployment and compatibility

Deploy with the companion frontend and explicit WEB_CLIENT_* configuration. The HTTPS proxy must forward WebSocket Upgrade to Console and protect legacy/raw browser WS bypasses. Docker frontend routing is included; the existing native frontend HTTP proxy needs an outer proxy to route this exact WS path directly to Console. Preserve native TCP/UDP ports and keys. Grants are process-local: use one Console instance or consistent affinity between grant requests and sockets.

The integration preserves upstream updater/bootstrap changes. Agent image build context includes the shared read-only collector. Documentation covers configuration, bypass protection, trust boundaries, scope, and rollback.

Validation

Local equivalents of official PR CI passed against the synchronized main baseline:

• Fresh npm ci, full ESLint, TypeScript, and Nest build.
• 38 Jest suites / 445 tests passed; the two opt-in MySQL cases skipped in that run were executed separately against MySQL 8.0 on Linux, 2/2 passed with the original timeout.
• 35 agent/network tests, 8 Linux entrypoint tests, and 20 upstream deployment/release/archive tests passed.
• Console and existing agent Docker images built successfully; SEA-compatible bundling succeeded.
• Final Console/frontend containers passed fresh SQLite startup, HTTP proxying, authenticated configuration projection, anonymous denial, read-only TCP reads, unknown-target denial, wrong-Origin rejection, and invalid-ticket closure through a real Nginx WS Upgrade.

Earlier paired real-device testing exercised authorization/revocation, native desktop/file authentication, media, transfers, recording, and administrative closure. That evidence is historical, not a claim that this final cleanup revision has completed every real-device matrix. No production deployment was performed for this final review.

Progress and remaining work

[████████░░] 8/10 review milestones complete

• Official-main integration and single-commit consolidation
• Role/device scope and manual-ID authorization
• Bound tickets, gateway validation, and revocation
• Audit integration and evidence boundaries
• Existing management integration and read-only TCP diagnostics
• Obsolete implementation/document cleanup
• Local official-CI equivalents
• Final paired-container HTTP/WS checks
• Broader OS/browser/native-version and long-session acceptance
• Maintainer/community review and follow-up polishing

Please keep this as a draft while the remaining compatibility and review work is completed.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 351b9ffc-61cf-4b1c-91e4-88854d9e709f

---

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[yardbirds0]

Hey @YuZhiYuanDev, the browser remote control work is ready for review now, along with the frontend PR.

It’s a pretty big change and still needs more real-world testing, so it’s beta for now. It’s usable, but the feature set is still fairly basic, and getting everything into good shape will take time and continued testing.

The foundation is in place now, though, and we can gradually build on it and improve it together.