feat(gateway-api): GitHub SSO via oauth2-proxy in front of dsh-gateway (#13)

Add oauth2-proxy (GitHub provider, org-restricted) as a reverse proxy in
front of the dsh-gateway, wired through the Traefik Gateway API. The gateway
inherits the authenticated GitHub username via X-Forwarded-User (SSO).

- gateway.py: opt-in AUTH_PROXY_HEADER trust, remote_user(), SSO bootstrap
  (auto-provision claim + mint/rotate token + session cookie), patch_token()
- 50-gateway.yaml: AUTH_PROXY_HEADER=X-Forwarded-User, COOKIE_SECURE=true
- gateway-api/dsh-demo: oauth2-proxy Deployment/Service + secret example,
  HTTPRoute backend -> oauth2-proxy:4180
- tests: 10 new SSO cases (106 passing)

Placeholders (dsh-demo.example.com, your-github-org) are substituted at
apply time.

Co-authored-by: SREDevOpsAgents <agents@sredevops.org>

gateway-api/dsh-demo/README.md

@@ -1,21 +1,47 @@
-# Gateway API — external access for `dsh-demo/dsh-gateway`
+# Gateway API — external access for `dsh-demo/dsh-gateway` (GitHub SSO)
 
 Exposes the `dsh-gateway` service (`dsh-demo`, port `8080`) outside the cluster
-using the Kubernetes Gateway API (Traefik Gateway controller).
+using the Kubernetes Gateway API (Traefik Gateway controller), fronted by
+**oauth2-proxy** so access requires a GitHub login restricted to a configured
+GitHub organization. The gateway inherits the authenticated GitHub username via
+the `X-Forwarded-User` header (SSO).
+
+## Request flow
+
+```
+Browser ──▶ Gateway dsh-gateway (HTTPS, TLS-terminate)
+  ──▶ HTTPRoute <your-hostname>
+    ──▶ oauth2-proxy:4180   (GitHub OAuth, org-restricted)
+      ──▶ dsh-gateway:8080  (X-Forwarded-User = GitHub login → SSO)
+```
 
 ## Resources
 
 | File | Kind | Purpose |
 |---|---|---|
 | `gateway.yaml` | `Gateway` | HTTPS listener with TLS termination |
-| `httproute.yaml` | `HTTPRoute` | Routes the hostname → `dsh-gateway:8080` |
+| `httproute.yaml` | `HTTPRoute` | Routes the hostname → `oauth2-proxy:4180` |
+| `oauth2-proxy.yaml` | `Deployment`/`Service` | GitHub OAuth reverse proxy |
+| `oauth2-proxy-secret.yaml.example` | `Secret` | Example OAuth credentials (not applied as-is) |
 | `tls-secret.yaml.example` | `Secret` | Example TLS cert secret (not applied as-is) |
 
 ## Prerequisites
 
-1. **Hostname** — replace the placeholder in `httproute.yaml` with the real FQDN.
-2. **TLS secret** — create `dsh-demo-tls` in `dsh-demo` (see `tls-secret.yaml.example`).
-3. **Ingress and DNS** — configure the upstream ingress and public DNS for the hostname.
+1. **GitHub OAuth App** — create one at
+   `https://github.com/settings/developers` with:
+   - Homepage URL: `https://dsh-demo.example.com`
+   - Authorization callback URL: `https://dsh-demo.example.com/oauth2/callback`
+   (replace `dsh-demo.example.com` with the actual public FQDN). Note the client
+   ID and client secret.
+2. **oauth2-proxy Secret** — `kubectl -n dsh-demo create secret generic oauth2-proxy`
+   with `client-id`, `client-secret`, and a `cookie-secret`
+   (`openssl rand -base64 32`). See `oauth2-proxy-secret.yaml.example`.
+3. **TLS secret** — create `dsh-demo-tls` in `dsh-demo` (see `tls-secret.yaml.example`).
+4. **Gateway app env** — the `dsh-gateway` Deployment must run the SSO-capable
+   image with `AUTH_PROXY_HEADER=X-Forwarded-User` and `COOKIE_SECURE=true`
+   (see `examples/dsh-agents-as-a-service/50-gateway.yaml`).
+5. **Ingress and DNS** — configure the upstream ingress and public DNS for the
+   hostname.
 
 ## Apply
 
@@ -25,17 +51,24 @@ kubectl apply -f gateway-api/dsh-demo/ --dry-run=server
 kubectl apply -f gateway-api/dsh-demo/
 ```
 
-> ⚠️ A write-enabled kubeconfig is required to create Gateways and HTTPRoutes.
+> ⚠️ A write-enabled kubeconfig is required to create Gateways, HTTPRoutes,
+> Deployments, and Secrets.
 
 ## Verify
 
 ```bash
-kubectl get gateway dsh-gateway -n dsh-demo -o yaml   # expect Programmed=True
-kubectl get httproute -n dsh-demo -o wide             # expect Accepted
-kubectl get endpoints dsh-gateway -n dsh-demo         # backend present
-kubectl -n dsh-demo exec deploy/dsh-gateway -- wget -qO- http://localhost:8080/healthz
+kubectl get gateway dsh-gateway -n dsh-demo -o yaml        # expect Programmed=True
+kubectl get httproute -n dsh-demo -o wide                  # backend oauth2-proxy:4180, Accepted
+kubectl get deploy oauth2-proxy -n dsh-demo                # 1/1 Ready
+kubectl get endpoints oauth2-proxy -n dsh-demo             # backend present
+kubectl -n dsh-demo logs deploy/oauth2-proxy --tail=50     # no config errors
 ```
 
+Browser check: open `https://<your-hostname>/` — you should be redirected
+to GitHub, and after signing in as a member of the allowed organization your
+sandbox opens with the session showing your GitHub login. A non-member is denied
+before reaching the gateway.
+
 ## Rollback
 
 ```bash
@@ -44,6 +77,14 @@ kubectl delete -f gateway-api/dsh-demo/
 
 ## Notes
 
-- No `ReferenceGrant` is required: the Gateway, HTTPRoute, and backend Service are
-  all in `dsh-demo`.
-- The backend (`dsh-gateway`) serves plain HTTP on 8080 and has a `/healthz` probe.
+- **SSO is opt-in and additive.** The gateway honors `X-Forwarded-User` only when
+  `AUTH_PROXY_HEADER` is set; unset it to restore bearer-token/session-only auth.
+- **Trust boundary.** After this change the `dsh-gateway` Service must be reachable
+  **only** through oauth2-proxy (it is a ClusterIP Service). A second Route/Ingress
+  that exposes `dsh-gateway:8080` directly would let clients spoof the header.
+- **GitHub login → DSH user.** GitHub usernames are lowercase alphanumerics and
+  hyphens, so they map 1:1 onto the gateway's dns-1123 `user` validation.
+- **Sign-out.** The gateway `/logout` clears `dsh_gw_session`; oauth2-proxy's own
+  session can be cleared at `/oauth2/sign_out` if desired.
+- No `ReferenceGrant` is required: the Gateway, HTTPRoute, oauth2-proxy, and the
+  backend Service are all in `dsh-demo`.