examples(mcp.proxy): wire identity guard for bearer pass-through to github

Adds a passthrough identity guard at north_http_server that captures the
inbound Authorization bearer via {credentials}, and references it from
south_mcp_client_github's options.authorization. mcp(client) re-stamps
Authorization: Bearer <token> on the outbound request to github:3003 so
github-mcp-server receives the client's PAT for its own validation.

The everything and time mcp(client) bindings remain unguarded — no
Authorization is added on outbound to those upstreams. Without a client
token, github-mcp-server's HTTP 403 + WWW-Authenticate (from --scope-challenge)
still flows back through the proxy unchanged.

README walks through the full client-driven auth flow end to end, and the
top-level examples index description is refreshed to match the current
demonstrated capabilities.

Author: claude

examples/README.md

@@ -50,7 +50,7 @@ Make sure you have the `latest` version of Zilla by running the `docker pull ghc
 | [http.kafka.proto.oneway](http.kafka.proto.oneway)           | Publish a Protobuf serialized object over HTTP onto a Kafka topic                         |
 | [http.kafka.sync](http.kafka.sync)                           | Correlates HTTP requests and responses over separate Kafka topics                         |
 | [http.proxy](http.proxy)                                     | Proxy request sent to the HTTP server from an HTTP client                                 |
-| [mcp.proxy](mcp.proxy)                                       | Aggregates multiple upstream MCP servers behind one JWT-guarded Streamable HTTP endpoint  |
+| [mcp.proxy](mcp.proxy)                                       | Aggregates multiple upstream MCP servers behind one Streamable HTTP endpoint, with per-route bearer pass-through to upstream  |
 | [mqtt.proxy.jwt](mqtt.proxy.jwt)                             | Proxies request sent to the MQTT server from a JWT-authorized MQTT client                 |
 | [mqtt.kafka.broker](mqtt.kafka.proxy)                        | Forwards MQTT publish messages to Kafka, broadcasting to all subscribed MQTT clients      |
 | [openapi.asyncapi.kakfa.proxy](openapi.asyncapi.kakfa.proxy) | Create an HTTP to Kafka REST proxy using OpenAPI and AsyncAPI schemas                     |

examples/mcp.proxy/README.md

@@ -30,11 +30,16 @@ The proxy demonstrates, in one configuration:
   through the gateway with no extra configuration. The `everything` reference
   server's `trigger-elicitation-request-async` and `simulate-research-query`
   (with `ambiguous: true`) tools exercise this directly.
-- **Upstream-driven auth** — the gateway adds no Authorization of its own.
-  Clients pass `Authorization: Bearer <PAT>` through Zilla to the upstream; if
-  the upstream needs additional scopes or rejects the token, it returns an MCP
-  scope-challenge elicitation and Zilla forwards that back to the client.
-  `github-mcp-server` is started with `--scope-challenge` to exercise this flow.
+- **Client → upstream bearer pass-through via the `identity` guard** — clients
+  send `Authorization: Bearer <PAT>` to Zilla; the `identity` guard captures
+  the token at `north_http_server` and `mcp(client)` for the github route
+  re-stamps it on the outbound request. The everything and time routes have no
+  guard configured, so no Authorization is added on outbound to those upstreams.
+- **Auth-driven challenge pass-through** — `github-mcp-server` is started with
+  `--scope-challenge`, so when an inbound token is missing or under-scoped the
+  upstream's `HTTP 403 + WWW-Authenticate` flows back through the gateway
+  unchanged. Clients that implement RFC 6750 / MCP OAuth can complete the
+  flow externally and retry with the new token.
 
 ## Requirements
 
@@ -97,19 +102,43 @@ JSON-RPC request bound for the client. Zilla forwards it back through
 Use MCP Inspector for a full interactive round-trip (it knows how to handle
 the elicitation message and reply via `elicitation/result`).
 
-### Call a GitHub tool (auth flows from client to upstream)
+### Call a GitHub tool (bearer flows from client through to upstream)
+
+First start the github upstream:
+
+```bash
+docker compose --profile github up -d
+```
+
+Issue a github tool call without an `Authorization` header — `github-mcp-server`
+returns `HTTP 403` with a `WWW-Authenticate` challenge that propagates back
+through the proxy:
+
+```bash
+curl -i -N http://localhost:7114/mcp \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json, text/event-stream" \
+    -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"github/get_me"}}'
+```
+
+Mint a [GitHub Personal Access Token](https://github.com/settings/tokens),
+then retry with `Authorization: Bearer <PAT>`. Zilla's `identity` guard captures
+the bearer at `north_http_server`, and the `mcp(client)` for the github route
+re-stamps it on the outbound request — `github-mcp-server` accepts the token
+and the tool call completes:
 
 ```bash
+export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...
 curl -N http://localhost:7114/mcp \
     -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"github/get_me"}}'
 ```
 
-Omit the `Authorization` header to observe `github-mcp-server`'s scope-challenge
-elicitation flowing back through the proxy — this is the same pass-through path
-as the `everything` example above, just driven by auth instead of a tool.
+The everything and time routes have no `options.authorization` on their
+`mcp(client)` bindings — they receive no Authorization header even when the
+client supplies one to Zilla.
 
 ### Observe the cache
 

examples/mcp.proxy/etc/zilla.yaml

@@ -1,5 +1,8 @@
 ---
 name: example
+guards:
+  passthrough:
+    type: identity
 stores:
   cache:
     type: memory
@@ -21,6 +24,11 @@ bindings:
     options:
       access-control:
         policy: cross-origin
+      authorization:
+        passthrough:
+          credentials:
+            headers:
+              authorization: Bearer {credentials}
     routes:
       - when:
           - headers:
@@ -77,6 +85,9 @@ bindings:
   south_mcp_client_github:
     type: mcp
     kind: client
+    options:
+      authorization:
+        name: passthrough
     routes:
       - exit: south_http_client
         with: