run-claude-gateway-ref

name	run-claude-gateway-ref
description	Launch and drive a local reference Claude apps gateway (claude gateway + Dex + Postgres) to probe, capture, or re-verify the login / managed-settings / OTLP-telemetry wire protocol that shunt's gateway superset (login → managed/settings → telemetry, epic

Run the reference Claude apps gateway (protocol probe)

Spins up the real claude gateway (built into the claude binary) with a local Dex IdP and throwaway Postgres, then drives the full device-flow login non-interactively with curl — no browser needed. Use it to (re)capture the wire contract shunt mirrors: exact token JSON, /managed/settings body, env push, OTLP relay behavior.

Everything is driven by .claude/skills/run-claude-gateway-ref/driver.sh (paths relative to repo root). Backend note: curl is sufficient — the /device browser page is scriptable once you send same-origin CSRF headers.

Prerequisites

• Docker running (pulls postgres:16-alpine, ghcr.io/dexidp/dex:v2.44.0)
• claude binary ≥ 2.1.207 (verified with 2.1.211), python3, curl
• Ports free: 8790 (gateway), 5556 (dex), 55432 (pg), 44318 (sink)

Run (agent path)

S=.claude/skills/run-claude-gateway-ref/driver.sh
$S up          # pg + dex containers, gateway on :8790, waits healthy
$S sink-start  # optional: local OTLP sink so the telemetry relay is observable
$S login       # full RFC 8628 device flow via curl → capture/token.json
$S probe       # captures protocol.md, managed_settings.json (+304), models.json,
               # refresh grant, POST /v1/metrics relay, /user/bootstrap
$S status      # health of all three processes
$S down        # kill gateway + sink, remove containers

Artifacts land in /tmp/shunt-gw-probe/capture/ (override root with GWREF_WORK). Gateway log: /tmp/shunt-gw-probe/gateway.log (audit events are JSON lines — evt: device.authorize, device.verify, session.mint, session.refresh, managed.serve, auth.denied). Sink log: /tmp/shunt-gw-probe/sink.log.

Login identity: [e-mail] / password (Dex static user, no groups).

Verified wire facts (2026-07-16, gateway 2.1.211)

Captured live; these fill the gaps docs/gateway-protocol.md marks unspecified:

• Token response (device grant AND refresh grant, same shape): {"access_token":"<HS256 JWT>","refresh_token":"<opaque>","token_type":"Bearer","expires_in":3600}. JWT claims: sub (IdP subject), email, name, aud=oidc client_id, iss=public_url. Refresh rotates the refresh token. Gateway refresh = refresh against the IdP (3500ms budget) + re-mint; IdP failure → 401 {"error":"invalid_grant"}.
• /managed/settings body: {"uuid":"sha256:…","checksum":"sha256:…","settings":{<managed-settings.json>}}, ETag = checksum, If-None-Match → 304. With telemetry.forward_to set it pushes six env vars (docs say five): CLAUDE_CODE_ENABLE_TELEMETRY=1, OTEL_{METRICS,LOGS,TRACES}_EXPORTER=otlp, OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>, OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf, merged with policy env.
• Discovery includes undocumented gateway_protocol_version: 1, token_endpoint_auth_methods_supported: ["none"], scopes_supported.
• IdP callback is {public_url}/oauth/callback (register in the IdP client).
• Telemetry relay is verbatim — body forwarded byte-identical, no identity attributes stamped by the gateway; POST /v1/{metrics,logs,traces} returns 200 even when the destination is down. Boot log says signals enabled: metrics for a bare forward_to entry.
• /v1/models is filtered by the caller's policy availableModels; full Anthropic shape (type, has_more, first_id, last_id).
• Error envelope adds top-level request_id alongside {"type":"error","error":{…}}.
• GET /user/bootstrap (new, Claude Desktop): 404 not_found_error unless a policy carries a desktop: block.

Gotchas

• POST /device is CSRF-guarded: without Origin + Referer + Sec-Fetch-Site: same-origin it returns 200 with "request came from another site and was blocked" instead of the 302 to the IdP. The audit log shows device.verify result=csrf_rejected.
• The gw_dev cookie from the /device POST must be replayed on /oauth/callback or the device grant is never approved.
• Dex latest (master) hangs forever on refresh (memory AND sqlite3 storage) → gateway session.refresh fails with "timed out after 3500ms" and the client gets invalid_grant. Pin v2.44.0.
• Loopback OIDC issuer is rejected by the SSRF guard unless CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 (driver sets it). http:// public_url is accepted on loopback.
• Don't let curl -w write into a JSON capture file — it corrupts the JSON and the next python3 json.load fails with "Extra data".
• The dummy upstreams API key boots fine; only /v1/messages inference would fail. Postgres is required at boot (gateway runs 6 migrations).

Troubleshooting

• refresh grant: 401 + gateway log "timed out after 3500ms" → your Dex image is unpinned/master; docker rm -f shunt-gw-dex and rerun up (pulls v2.44.0).
• device POST did not redirect from the driver → CSRF headers missing (driver sends them; check you didn't proxy/strip them).
• Boot fails on config: unknown keys fail fast with a field-level error; check /tmp/shunt-gw-probe/gateway.log first.