Trusted Browsers and Devices

Trusted browsers and trusted devices are the local keys that open protected workspace data. They are different access paths and stay separate in both product behavior and operational policy.

They exist as part of Workspace Protection, which requires an Enterprise workspace. In non-Enterprise workspaces, normal account, project, token, and tunnel permissions still apply, but there is no workspace-wide trusted browser/device key model.

This separation matters in enterprise environments. A browser profile, an operator CLI, a long-running agent, and a service account do not have the same lifecycle or risk profile. Workspace Protection treats them as distinct cryptographic devices.

Workspace Protection has two daily access paths and one offline recovery path. Browsers and devices are used for normal work; the Recovery Kit is the fallback.

Workspace Protection
        |
        +--> trusted browsers
        |       Dashboard, browser terminal, browser replay
        |
        +--> trusted devices
        |       CLI, rstream ui, agents, services
        |
        +--> Recovery Kit
                offline recovery path

A protected operation needs account authorization and a trusted local key. The local key can live in a browser profile or in a device file, but it is never implied by login alone.

Trusted browsers

A trusted browser is used by the Dashboard and browser UI flows. Its private keys live in browser storage for the current browser profile. If that profile is deleted, reset, or moved without the key material, that trusted browser access path is lost.

Trusted browsers can open protected workspace settings, review pending browser/device requests, and decrypt protected data in browser UI flows.

Users see their own browser access clearly. Owners and admins can review broader workspace access through administrative views designed for many users and many devices.

Browser trust records are scoped to the current workspace and user. Members see the access state for their own browsers and devices. Owners and admins use a separate administrative view to search accounts, inspect trusted access paths, and revoke keys when required.

Typical browser states:

Trusted devices

A trusted device is used by local CLI, agent, service, and automation workflows. Its private keys live under the local rstream workspace directory:

~/.rstream/workspaces/<workspace-id>/devices/<device-id>.json
~/.rstream/workspaces/<workspace-id>/webtty/identities/<device-id>.identity.json

Enroll a CLI device:

rstream workspace device enroll --kind cli --label operator-cli

Check local trust status:

rstream workspace device status

Use --kind cli for an operator CLI, --kind agent for an automated agent, and --kind service for a service process. The kind helps owners and admins understand what they are approving and later revoking.

Those commands use the workspace attached to the active project context. If the machine has no active project context, or if the device belongs to another workspace, list the workspaces available to the current CLI account:

rstream workspace list

Then enroll the local machine with an explicit workspace id:

rstream workspace device enroll --workspace <workspace-id> --kind cli --label workstation

The command creates local device material and a pending request. It does not make the device trusted by itself. A trusted owner/admin must approve the request after comparing the verification code.

After approval, the same command family shows the local state:

rstream workspace device status

Use rstream workspace device status --workspace <workspace-id> when checking a workspace other than the one attached to the active project context.

For automation, keep the device file under the service account that will run the process. Do not enroll a personal laptop and then copy the device file into a CI runner unless the organization intentionally wants the same trusted key to exist in both places.

Approval and verification codes

New browsers and devices generate private keys locally. rstream receives public keys and proof metadata, not the private keys.

Approval uses a short verification code derived from the pending public keys, workspace id, device kind, optional WebTTY key material, and fingerprint. The requester and approver must compare the same code before approval.

If the codes do not match, reject the request. A mismatch means the two parties are not approving the same public key material.

The verification code protects the approval step by making both sides confirm the same pending public key material before a trusted approver wraps workspace keys for the requester.

requester
  shows verification code ABCD-EFGH
        |
        | out-of-band comparison
        v
trusted approver
  sees the same pending request and code ABCD-EFGH
        |
        | approves and wraps workspace keys locally
        v
requester receives encrypted envelope

The verification code is not a password. It is a human-checkable commitment to the public key material being approved. The requester and approver compare it over a trusted channel, such as an internal call, screen share, incident bridge, or in-person approval.

Revocation and lost devices

Revoking a browser or device removes future access to protected workspace material for that key. It does not automatically rotate the whole workspace keyset.

Mark a key as lost when the device is gone and the private key is not suspected to be exposed. Revoke it when the key may have been exposed. Organization policy then decides whether the Recovery Kit or other protected material also needs rotation.

Revocation is explicit and auditable:

Revoked keys can remain in administrative history for audit and incident review. They are excluded from the normal trusted browser list unless a historical access view is explicitly selected.

WebTTY behavior

Workspace-managed WebTTY clients use trusted device material automatically during registered server resolution. Users do not pass WebTTY recipient keys on each command for a workspace-managed server.

For non-workspace-managed WebTTY targets, clients keep the shorter path where possible: live engine inventory, WebTTY labels, and local known-server entries decide whether E2E is required and which local identity to use. Workspace-managed clients resolve trusted device grants through the Control plane because those grants are workspace state. The WebTTY server uses the public trust material pinned during enrollment and does not call the Control plane during a terminal session.

If the local CLI is not a trusted workspace device, a workspace-managed E2E WebTTY connection fails before terminal content is sent. If the browser is not trusted, browser UI cannot decrypt protected session data even if the user is otherwise allowed to see the workspace.

For registered WebTTY servers, runtime resolution chooses the E2E path automatically. The connection command stays simple, and trust material is loaded during server resolution.

rstream webtty exec --url rstrm://prod-shell -- whoami
        |
        | resolve registered server and project policy
        v
workspace-managed E2E required
        |
        | load trusted workspace device material
        v
connect only if decrypt/encrypt keys are available

Users do not pass an extra --e2e flag for a registered server whose policy already requires workspace-managed encryption. Explicit-key setups may still pass local trust material directly when the operator wants a known-host workflow outside Workspace Protection.