hermes-agent/website/docs/user-guide
victor-kyriazakos e9579a9896
feat(relay): ambient token endpoint mode for gateway.idp.token_url (#84074)
* feat(relay): ambient token endpoint mode for gateway.idp.token_url

When gateway.idp.token_url is configured WITHOUT client_id/client_secret,
treat the URL as a metadata-server-style ambient credential endpoint:
plain GET, response body is the token (raw JWT or {"access_token": ...}
JSON envelope). Covers workload-identity proxies such as Domino's
$DOMINO_API_PROXY/access-token, which mint short-lived user-scoped OIDC
tokens with no client registration.

Previously this configuration was a hard error (client_id/client_secret
missing), so no working deployment changes behaviour: creds present keeps
the OAuth2 client_credentials POST, no token_url keeps Nous Portal. The
misconfig error now self-diagnoses (names the ambient fallback and how to
select the client_credentials grant instead).

* fix(relay): reject short plain-text bodies in ambient token shape gate

Review finding: the shape gate accepted any base64url-alphabet word, so an
IdP answering the ambient GET with a terse error body ('unauthorized',
'error', 'null') had that word returned as a bearer token instead of the
fail-closed misconfiguration error. Tighten the gate to JWT-like dotted
tokens (3+ segments) or long opaque tokens (>= 32 chars); short bare words
now raise the self-diagnosing ambient error.

* fix(relay): partial IdP client credentials keep the loud error, never select ambient GET

The ambient-endpoint dispatch used 'not client_id or not client_secret',
so configuring exactly one credential (a mistyped client_credentials
setup) silently issued a GET at the IdP token endpoint and then raised
'no client_id/client_secret configured' — factually wrong for that
operator, and a stray request the old hard error never made.

Ambient mode now requires NEITHER credential; a partial pair raises
immediately, names the missing key, and issues no HTTP request (tests
assert urlopen is never called). Docstring and relay.md now say
'neither' instead of 'without'.

* fix(relay): ambient JSON envelope requires a string access_token, no coercion

Review finding (P2): the JSON-envelope branch accepted any truthy
access_token via str() coercion — a number became '12345…', a boolean
became 'True', an object became its Python repr — bypassing the fail-
closed contract and deferring the failure to the connector, where it
hides the real endpoint problem.

The envelope value must now be a non-empty string, the same contract the
client_credentials path enforces on its token response. Deliberately NO
shape gate on envelope values: an envelope is an intentional token
response (mode-1 symmetry), and opaque tokens may use the standard-base64
alphabet the raw-body gate rejects. Mutation check: reverting the branch
to str() coercion sends the 3 coercion tests red (3 failed, 15 passed).

---------

Co-authored-by: Ben Barclay <ben@nousresearch.com>
2026-08-12 10:06:28 +10:00
..
egress Reapply "Merge pull request #30179 from NousResearch/feat/iron-proxy" 2026-07-24 09:49:00 -07:00
features feat(kanban): teach workers to flag collision hotspots instead of piling on 2026-08-10 13:11:19 -07:00
messaging feat(relay): ambient token endpoint mode for gateway.idp.token_url (#84074) 2026-08-12 10:06:28 +10:00
secrets docs: accuracy sweep + coverage for 2 months of shipped features 2026-07-29 08:48:05 -07:00
skills fix(security): remove blender MCP catalog entry and skill after upstream compromise 2026-08-10 12:12:11 -07:00
_category_.json
…
checkpoints-and-rollback.md fix(checkpoints): never auto-delete orphans on unattended startup sweep 2026-07-24 16:01:06 -07:00
cli.md feat(cli): show session titles in status bars 2026-08-08 17:02:55 -07:00
configuration.md fix(runtime): make nofile soft limit configurable 2026-08-10 17:02:56 -07:00
configuring-models.md docs: teach providers: dict as the canonical custom-provider format 2026-07-29 09:44:59 -07:00
desktop.md feat(desktop): add terminal font picker 2026-08-01 14:30:08 -07:00
docker.md feat(runtime)!: require Node 26 across all installers, heal, and upgrade paths 2026-08-01 21:17:51 -04:00
git-worktrees.md docs(developer-guide): document htui/hgui worktree UI dev helpers (#64783) 2026-07-16 22:51:23 -04:00
import-from-other-agents.md feat(cli): hermes import-agent — import Claude Code and Codex CLI setups 2026-07-26 17:47:07 -07:00
managed-scope.md
…
multi-profile-gateways.md feat(gateway): allow selective multiplex profile serving 2026-08-10 22:48:24 -07:00
profile-distributions.md Expand .gitignore example 2026-06-20 20:42:49 -07:00
profiles.md docs: warn against pointing two agents at one Hermes home (memory, profiles, FAQ) 2026-08-05 21:33:44 +05:30
security.md Revert "remove Vercel AI Gateway and Vercel Sandbox (#33067)" 2026-07-29 19:48:37 -07:00
sessions.md docs(sessions): document repair-routing and the continuity guarantees 2026-08-09 23:29:16 -07:00
tui.md feat(cli): show session titles in status bars 2026-08-08 17:02:55 -07:00
which-file-does-what.md docs: add 'Which File Does What?' - one-page map of SOUL/USER/MEMORY/AGENTS 2026-08-05 21:33:44 +05:30
windows-native.md docs: fix stale PATH location in windows-native common pitfalls 2026-08-05 21:33:44 +05:30
windows-wsl-quickstart.md
…