#17127: fix(webchat): include operator.read and operator.write in connect scopes
app: macos
app: web-ui
size: M
trusted-contributor
Cluster:
Device Pairing and Gateway Fixes
## Problem
After the 2026.2.14 update, webchat clients accessing the gateway via LAN IP (not localhost) receive `missing scope: operator.read` errors for all RPC calls. This makes the web UI completely unusable.
Reported in #16820 and #16862 with many affected users.
## Root Cause
The webchat client was only requesting these scopes during connect:
- `operator.admin`
- `operator.approvals`
- `operator.pairing`
While `operator.admin` semantically implies full access, the scope validation in `server-methods.ts` explicitly checks for `operator.read` or `operator.write` for READ_METHODS and WRITE_METHODS sets:
```typescript
if (READ_METHODS.has(method) && !(scopes.includes(READ_SCOPE) || scopes.includes(WRITE_SCOPE))) {
return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.read");
}
```
The admin scope check happens first and should return early, but there may be edge cases in the device pairing flow where scopes aren't properly propagated.
## Fix
Explicitly include `operator.read` and `operator.write` in the webchat connect scopes. This ensures the client has the required scopes regardless of how they're stored/validated during the pairing flow.
## Testing
- Verified lint and format pass
- The fix is defensive and additive (adding scopes that should already be implied by `operator.admin`)
Fixes #16820
Fixes #16862
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Added `operator.read` and `operator.write` to webchat connect scopes to fix "missing scope: operator.read" errors when accessing gateway via LAN IP.
- Root cause: After commit `cfd11295` (2026-02-09), automatic `operator.admin` grants were removed for security hardening
- When webchat clients connect via LAN IP without device identity, scopes get cleared at `message-handler.ts:431` for security
- Even though `operator.admin` semantically implies full access and has an early-return check at `server-methods.ts:117-119`, the scope clearing in the pairing flow prevents it from being available
- This fix explicitly includes `operator.read` and `operator.write` so they're present even if admin scope gets cleared during pairing
- The change is defensive and additive, maintaining backward compatibility while ensuring the UI remains functional
<h3>Confidence Score: 5/5</h3>
- Safe to merge - minimal additive change that fixes critical regression
- The fix addresses a regression introduced in commit `cfd11295` by explicitly requesting the necessary scopes. The change is minimal (adds 2 scope strings to an array), defensive (adds scopes that should be implied by operator.admin), and backward compatible (doesn't remove any existing scopes). No logic changes or architectural modifications.
- No files require special attention
<sub>Last reviewed commit: 7eecadf</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#17753: fix: Control UI unusable over HTTP - missing scopes
by MisterGuy420 · 2026-02-16
85.9%
#17195: fix: Add operator.read/write scopes to Dashboard auto-pairing
by MisterGuy420 · 2026-02-15
85.2%
#22583: fix(gateway): add operator.write to scope hierarchy (#22574)
by lailoo · 2026-02-21
84.1%
#21622: fix(gateway): include read/write in CLI default operator scopes
by zerone0x · 2026-02-20
83.9%
#22666: fix(gateway): operator.admin should imply all operator scopes
by maximveksler · 2026-02-21
83.9%
#17205: fix: enforce full operator scopes for Control UI and Webchat auto-p...
by Limitless2023 · 2026-02-15
83.8%
#12802: fix(gateway): default unscoped operator connections to read-only
by yubrew · 2026-02-09
81.9%
#21476: fix(cli): include operator.read in default CLI scopes
by heyrtl · 2026-02-20
81.6%
#23708: fix(gateway): auto-approve scope upgrades for loopback clients
by widingmarcus-cyber · 2026-02-22
81.4%
#23039: fix: subagent announce fails with pairing required due to missing o...
by ascott · 2026-02-21
80.2%