docs(gateway): clarify backend RPC pairing

This commit is contained in:
Peter Steinberger
2026-04-25 23:24:36 +01:00
parent d74b6359fd
commit 41b27024bb
2 changed files with 12 additions and 2 deletions

View File

@@ -577,11 +577,13 @@ rather than the pre-handshake defaults.
trusted shared-secret helper flows.
- Same-host tailnet or LAN connects are still treated as remote for pairing and
require approval.
- All WS clients must include `device` identity during `connect` (operator + node).
Control UI can omit it only in these modes:
- WS clients normally include `device` identity during `connect` (operator +
node). The only device-less operator exceptions are explicit trust paths:
- `gateway.controlUi.allowInsecureAuth=true` for localhost-only insecure HTTP compatibility.
- successful `gateway.auth.mode: "trusted-proxy"` operator Control UI auth.
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, severe security downgrade).
- direct-loopback `gateway-client` backend RPCs authenticated with the shared
gateway token/password.
- All connections must sign the server-provided `connect.challenge` nonce.
### Device auth migration diagnostics

View File

@@ -383,6 +383,14 @@ child session is marked `abortedLastRun: true`. Those restart-aborted child
sessions remain recoverable through the sub-agent orphan recovery flow, which
sends a synthetic resume message before clearing the aborted marker.
If a sub-agent spawn fails with Gateway `PAIRING_REQUIRED` / `scope-upgrade`,
check the RPC caller before editing pairing state. Internal `sessions_spawn`
coordination should connect as `client.id: "gateway-client"` with
`client.mode: "backend"` over direct loopback shared-token/password auth; that
path does not depend on the CLI's paired-device scope baseline. Remote callers,
explicit `deviceIdentity`, explicit device-token paths, and browser/node clients
still need normal device approval for scope upgrades.
## Stopping
- Sending `/stop` in the requester chat aborts the requester session and stops any active sub-agent runs spawned from it, cascading to nested children.