hermes-plugin-pocketid-auth

A Hermes Agent dashboard auth provider that authenticates the web dashboard against a self-hosted PocketID OpenID Connect identity provider.

• OIDC authorization-code + PKCE (S256) — works with public clients (no secret)
• RS256 JWT verification against the instance JWKS
• Enriches the dashboard display name from the OIDC userinfo endpoint (PocketID access tokens are bare JWTs, so the human-readable name isn't in the token itself)
• Refresh-token support; logout is client-side cookie clearing

Install

hermes plugins install ericjdunphy/hermes-plugin-pocketid-auth --enable

This clones the repo into ~/.hermes/plugins/ (or your active profile's plugins dir) and enables it. Because it's a user-installed backend plugin, it must be opted into plugins.enabled — --enable does that for you.

Configure

In PocketID, create an OIDC client for the Hermes dashboard with the redirect URI https://<your-dashboard-host>/auth/callback. Then configure Hermes via either config.yaml (canonical) or environment variables (override).

config.yaml:

dashboard:
  auth:
    provider: pocket_id        # select this provider
  pocket_id:
    issuer_url: https://id.example.com
    client_id:  hermes-dashboard
    client_secret: ""          # optional — omit/blank for a public PKCE client

Environment (wins over config.yaml when set non-empty):

HERMES_POCKETID_ISSUER_URL=https://id.example.com
HERMES_POCKETID_CLIENT_ID=hermes-dashboard
HERMES_POCKETID_CLIENT_SECRET=        # optional

Restart the dashboard after changes (plugins load at startup).

Requirements

PyJWT (with crypto), httpx, and cryptography — all shipped with Hermes. If you run a stripped environment, pip install -r requirements.txt.

How it works

OIDC endpoint	Path
discovery	/.well-known/openid-configuration
authorize	/authorize
token	/api/oidc/token
userinfo	/api/oidc/userinfo
JWKS	/.well-known/jwks.json

The JWKS fetch sends an explicit User-Agent because some reverse proxies / WAFs in front of PocketID return HTTP 403 for the default Python-urllib agent.

License

MIT