feat(gateway): negotiate scoped WebSocket grants

[ericlewis]

What does this PR do?

Adds an opt-in, versioned authorization contract for native and other external clients on the existing /api/ws JSON-RPC transport.

An authenticated client can request a single-use hermes.mobile ticket with explicit conversation scopes. The resulting server-derived grant is carried through upgrade, reported in the additive gateway.ready payload, and enforced by a fail-closed method and parameter policy before handlers run.

Bodyless dashboard ticket minting, internal credentials, loopback tokens, stdio dispatch, and the existing skin ready field remain compatible.

This is a draft for maintainer feedback on contract naming, versioning, and the intentionally narrow v1 boundary.

Related Issue

Fixes #62857

Type of Change

• Bug fix
• New feature
• Security fix
• Documentation update
• Tests
• Refactor
• New skill

Changes Made

• Extend POST /api/auth/ws-ticket with an opt-in mobile audience and validated explicit scopes while preserving the bodyless legacy response.
• Carry the effective ticket grant through /api/ws and report server, protocol, contract, schema, capability, and authorization metadata in gateway.ready.
• Enforce a minimum mobile method and parameter allowlist with structured missing or non-grantable scope errors.
• Keep shell, configuration, credential, plugin, process, deletion, permanent-policy, approval, account, and unmapped methods unavailable.
• Require read access in every mobile grant; require write plus control to create live sessions.
• Prevent write-scoped busy submissions from interrupting, steering, or seizing another client in-flight transport.
• Add public cookie login to ticket mint to real WebSocket upgrade to ready and denied-dispatch coverage.

Security Boundary

The mobile ticket is connection attenuation, not a persistent device credential or a replacement for the existing auth gate. It is accepted only on /api/ws, remains single-use with the existing TTL, and cannot authorize hidden parameters such as profile, cwd, seeded system history, model or provider overrides, transcript truncation, or future fields.

Replay cursors, mutation idempotency, and stable addressable approvals are intentionally not advertised by this slice.

How to Test

1. Run the hermetic auth and gateway selection:

scripts/run_tests.sh tests/tui_gateway tests/test_tui_gateway_loop_noise.py tests/test_tui_gateway_queue_on_busy.py tests/test_tui_gateway_server.py tests/test_tui_gateway_ws.py tests/hermes_cli/test_dashboard_auth_*.py -q

2. Run Ruff on the ten changed Python files.
3. Run git diff --check and scripts/check-windows-footguns.py --diff main.

Refreshed onto current official main f67aae3; head d8bc3bc.

Local result: 44 files, 975 tests passed, 0 failed on macOS 27.0. Ruff, diff check, and Windows-footgun scan pass. The full repository suite was not run locally and is left to CI.

Checklist

Code

• Read CONTRIBUTING.md and AGENTS.md
• Conventional commit messages
• Searched open and merged issues and PRs for duplicates
• Focused change with no unrelated dependency or config updates
• Full pytest tests/ -q suite run locally
• Added behavior and public-boundary tests
• Tested on macOS 27.0

Documentation and Housekeeping

• Relevant module and API docstrings updated; broader client docs deferred pending contract feedback
• cli-config.yaml.example N/A
• Contributor workflow docs N/A
• Cross-platform impact considered and Windows-footgun scan passed
• Tool descriptions and schemas N/A

Screenshots / Logs

No UI change. Focused hermetic result: 975 passed, 0 failed.

[teknium1]

Thanks for the narrowly scoped gateway authorization work. The premise is present on current main: /api/ws authenticates and then calls handle_ws(ws) without an authorization grant (hermes_cli/web_server.py:15593-15603), while the dispatcher routes normalized requests directly to handlers (tui_gateway/server.py:1270-1285).

The proposed pre-dispatch, fail-closed mobile policy is at the correct transport boundary, preserves the legacy ticket path, and includes focused ticket, upgrade, dispatch, parameter-denial, and busy-transport coverage. I found no concrete blocking defect in static review.

Automated hermes-sweeper review.

[freemanconsulting]

Superseded by #72635, which reconstructs this scoped mobile WebSocket authorization contract on current main while preserving the original Eric Lewis commit authorship. The replacement integrates current process-isolation, busy-session, transport-ownership, MCP-startup, and desktop recovery behavior; adds current-path end-to-end mobile ticket/WebSocket/dispatch coverage; and has passed the full required GitHub CI matrix. The original branch remains read-only to the replacement PR author, so it cannot be safely refreshed in place.