mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-18 04:41:56 +00:00
3b9368a0c4
Two loopback-redirect OAuth flows (xAI Grok, Spotify) silently fail when Hermes runs on a remote host: the auth server redirects to 127.0.0.1:<port> on the user's laptop, not on the remote box. The --no-browser flag only suppresses webbrowser.open() — it doesn't change the bind address. Symptom xAI surfaces is 'Could not establish connection. We couldn't reach your app.', followed by a 'xAI authorization timed out waiting for the local callback' on the CLI side. Changes - hermes_cli/auth.py: new _print_loopback_ssh_hint() helper, called from _xai_oauth_loopback_login() and _spotify_login() right after they print the redirect URI. Silent off SSH; on SSH prints the exact 'ssh -N -L <port>:127.0.0.1:<port>' command using the actually-bound port (not the hardcoded constant — the listener auto-bumps when the preferred port is busy), a provider-specific docs URL, and a link to the new shared guide. - website/docs/guides/oauth-over-ssh.md (new): single source of truth for the tunnel pattern — TL;DR command, jump-box / ProxyJump variant, mosh+tmux+ControlMaster gotchas, troubleshooting. - website/docs/guides/xai-grok-oauth.md: fix the two sections that claimed --no-browser alone was enough; link to the shared guide. - website/docs/user-guide/features/spotify.md: expand the existing one-liner; link to the shared guide. - website/sidebars.ts: register the new page. - tests/hermes_cli/test_auth_loopback_ssh_hint.py: 7 unit tests covering SSH-vs-not, loopback-vs-not, malformed URIs, port echo, with and without provider docs URL.
95 lines
3.7 KiB
Python
95 lines
3.7 KiB
Python
"""Unit tests for _print_loopback_ssh_hint() in hermes_cli/auth.py.
|
|
|
|
The helper exists to warn users that loopback OAuth flows (xAI Grok OAuth,
|
|
Spotify) don't work over SSH unless they set up an `ssh -L` port forward
|
|
between their laptop's browser and the remote host's loopback listener.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import io
|
|
import contextlib
|
|
|
|
import pytest
|
|
|
|
from hermes_cli import auth as auth_mod
|
|
|
|
|
|
def _cap(fn):
|
|
buf = io.StringIO()
|
|
with contextlib.redirect_stdout(buf):
|
|
fn()
|
|
return buf.getvalue()
|
|
|
|
|
|
def test_loopback_ssh_hint_silent_when_not_remote(monkeypatch):
|
|
monkeypatch.setattr(auth_mod, "_is_remote_session", lambda: False)
|
|
out = _cap(lambda: auth_mod._print_loopback_ssh_hint(
|
|
"http://127.0.0.1:56121/callback", docs_url=auth_mod.XAI_OAUTH_DOCS_URL
|
|
))
|
|
assert out == ""
|
|
|
|
|
|
def test_loopback_ssh_hint_prints_tunnel_command_on_ssh(monkeypatch):
|
|
monkeypatch.setattr(auth_mod, "_is_remote_session", lambda: True)
|
|
out = _cap(lambda: auth_mod._print_loopback_ssh_hint(
|
|
"http://127.0.0.1:56121/callback", docs_url=auth_mod.XAI_OAUTH_DOCS_URL
|
|
))
|
|
# Must include the exact ssh -L command with the port from the redirect URI
|
|
assert "ssh -N -L 56121:127.0.0.1:56121" in out
|
|
# Must include the provider-specific docs URL
|
|
assert auth_mod.XAI_OAUTH_DOCS_URL in out
|
|
# Must always include the cross-provider SSH guide
|
|
assert auth_mod.OAUTH_OVER_SSH_DOCS_URL in out
|
|
|
|
|
|
def test_loopback_ssh_hint_uses_actual_bound_port(monkeypatch):
|
|
"""When the preferred port is busy, _xai_start_callback_server falls back to
|
|
an OS-assigned port. The hint must echo whichever port actually got bound,
|
|
not the hardcoded constant."""
|
|
monkeypatch.setattr(auth_mod, "_is_remote_session", lambda: True)
|
|
out = _cap(lambda: auth_mod._print_loopback_ssh_hint(
|
|
"http://127.0.0.1:51234/callback", docs_url=auth_mod.XAI_OAUTH_DOCS_URL
|
|
))
|
|
assert "ssh -N -L 51234:127.0.0.1:51234" in out
|
|
assert "56121" not in out
|
|
|
|
|
|
def test_loopback_ssh_hint_silent_for_non_loopback_uri(monkeypatch):
|
|
"""Defense in depth: if a future caller passes a non-loopback redirect URI
|
|
by mistake, we don't tell the user to forward an external port."""
|
|
monkeypatch.setattr(auth_mod, "_is_remote_session", lambda: True)
|
|
out = _cap(lambda: auth_mod._print_loopback_ssh_hint(
|
|
"https://example.com/callback", docs_url=auth_mod.XAI_OAUTH_DOCS_URL
|
|
))
|
|
assert out == ""
|
|
|
|
|
|
def test_loopback_ssh_hint_silent_for_malformed_uri(monkeypatch):
|
|
monkeypatch.setattr(auth_mod, "_is_remote_session", lambda: True)
|
|
out = _cap(lambda: auth_mod._print_loopback_ssh_hint(
|
|
"not-a-uri", docs_url=auth_mod.XAI_OAUTH_DOCS_URL
|
|
))
|
|
assert out == ""
|
|
|
|
|
|
def test_loopback_ssh_hint_works_without_provider_docs_url(monkeypatch):
|
|
monkeypatch.setattr(auth_mod, "_is_remote_session", lambda: True)
|
|
out = _cap(lambda: auth_mod._print_loopback_ssh_hint(
|
|
"http://127.0.0.1:43827/spotify/callback"
|
|
))
|
|
assert "ssh -N -L 43827:127.0.0.1:43827" in out
|
|
# Generic SSH guide is always present even without a provider-specific URL
|
|
assert auth_mod.OAUTH_OVER_SSH_DOCS_URL in out
|
|
# Should not falsely show "Provider docs:" when no docs_url was passed
|
|
assert "Provider docs:" not in out
|
|
|
|
|
|
def test_loopback_ssh_hint_accepts_localhost_hostname(monkeypatch):
|
|
"""The constant is 127.0.0.1, but parsing tolerates `localhost` too in case
|
|
a future caller normalizes the URI differently."""
|
|
monkeypatch.setattr(auth_mod, "_is_remote_session", lambda: True)
|
|
out = _cap(lambda: auth_mod._print_loopback_ssh_hint(
|
|
"http://localhost:56121/callback"
|
|
))
|
|
assert "ssh -N -L 56121:127.0.0.1:56121" in out
|