Add unauthenticated /reflect endpoint for live DIFC label snapshots in gateway and proxy modes (#7168)

This change adds a runtime reflection endpoint to inspect current DIFC
agent label state, which was previously not exposed. `GET /reflect` now
returns all known agent IDs with their secrecy/integrity labels, plus
current enforcement mode and a timestamp.

- **Shared reflect payload builder**
- Added `difc.BuildReflectResponse(...)` to produce a consistent
snapshot shape:
    - `agents` map (`agentID -> {secrecy, integrity}`)
    - `mode` (strict/filter/propagate)
    - `timestamp` (RFC3339 UTC)
  - Output normalizes tag arrays to sorted string slices.

- **Gateway support (routed + unified)**
  - Added `server.HandleReflect(...)`.
- Registered `/reflect` in common endpoint wiring, so it is available in
both gateway HTTP modes.
- Endpoint is intentionally **unauthenticated** per current requirement.

- **Proxy support**
  - Added `GET /reflect` handling in proxy HTTP handler.
- Works with normal paths and GH-host-prefixed paths
(`/api/v3/reflect`).

- **Focused coverage for reflect behavior**
  - Added tests for:
    - gateway routed + unified availability
    - unauthenticated access with API key configured
    - populated and empty registry snapshots
    - proxy `/reflect` and `/api/v3/reflect`
    - defensive handling of nil registry entries

```json
{
  "agents": {
    "proxy": {
      "secrecy": ["repo:github/private-repo"],
      "integrity": ["approved"]
    },
    "abc123def456": {
      "secrecy": [],
      "integrity": ["unapproved"]
    }
  },
  "mode": "propagate",
  "timestamp": "2026-06-07T13:40:00Z"
}
```

Author: lpcox

README.md

@@ -225,6 +225,29 @@ For the full gateway field list (including rate limiting, tracing, keepalive, an
 - `POST /mcp/{serverID}` — Routed mode (default): JSON-RPC request to specific server
 - `POST /mcp` — Unified mode: JSON-RPC request routed to configured servers
 - `GET /health` — Health check; returns JSON `{"status":"healthy" | "unhealthy","specVersion":"...","gatewayVersion":"...","servers":{...}}`
+- `GET /reflect` — Unauthenticated DIFC label snapshot for all known agents (gateway and proxy mode)
+
+### `GET /reflect` response schema
+
+```json
+{
+  "agents": {
+    "<agent-id>": {
+      "secrecy": ["<tag>"],
+      "integrity": ["<tag>"]
+    }
+  },
+  "mode": "strict|filter|propagate",
+  "timestamp": "RFC3339 UTC timestamp"
+}
+```
+
+- `agents`: map keyed by agent ID with current DIFC labels.
+- `secrecy`/`integrity`: sorted arrays of label tags (empty array when none).
+- `mode`: active DIFC enforcement mode.
+- `timestamp`: snapshot generation time in UTC (`time.RFC3339`).
+
+> Security note: `/reflect` is intentionally unauthenticated for local/runtime debugging and operational introspection. It exposes active agent IDs and current DIFC labels, so operators should only expose the gateway/proxy on trusted networks.
 
 Supported MCP methods: `tools/list`, `tools/call` (proxied to backend servers), plus standard lifecycle methods (`initialize`, etc.) handled natively by the MCP SDK.
 

docs/PROXY_MODE.md

@@ -60,6 +60,33 @@ gh CLI  →  awmg proxy (localhost:8443, TLS)  →  api.github.com
 
 Write operations (PUT, POST, DELETE, PATCH) pass through unmodified.
 
+## Reflect Endpoint
+
+Proxy mode exposes an unauthenticated DIFC reflection endpoint:
+
+- `GET /reflect`
+- `GET /api/v3/reflect` (`GH_HOST` style REST base path used by `gh` against GHES/proxy targets; normalized to `/reflect`)
+
+Response schema:
+
+```json
+{
+  "agents": {
+    "<agent-id>": {
+      "secrecy": ["<tag>"],
+      "integrity": ["<tag>"]
+    }
+  },
+  "mode": "strict|filter|propagate",
+  "timestamp": "RFC3339 UTC timestamp"
+}
+```
+
+- `agents`: map of known agent IDs to current DIFC labels.
+- `secrecy`/`integrity`: sorted label arrays in ascending lexicographic order (empty when no labels are present).
+- `mode`: current DIFC enforcement mode.
+- `timestamp`: snapshot creation time in UTC (`time.RFC3339`).
+
 ## Flags
 
 | Flag | Default | Description |

internal/difc/reflect.go

@@ -0,0 +1,51 @@
+package difc
+
+import (
+	"sort"
+	"time"
+)
+
+// ReflectedAgentLabels is the JSON shape for an agent's current DIFC labels.
+type ReflectedAgentLabels struct {
+	Secrecy   []string `json:"secrecy"`
+	Integrity []string `json:"integrity"`
+}
+
+// ReflectResponse is the JSON response returned by /reflect endpoints.
+type ReflectResponse struct {
+	Agents    map[string]ReflectedAgentLabels `json:"agents"`
+	Mode      string                          `json:"mode"`
+	Timestamp string                          `json:"timestamp"`
+}
+
+// BuildReflectResponse returns a snapshot of all known agent labels.
+func BuildReflectResponse(components DIFCComponents) ReflectResponse {
+	agents := map[string]ReflectedAgentLabels{}
+	if components.AgentRegistry != nil {
+		for _, agentID := range components.AgentRegistry.GetAllAgentIDs() {
+			agent, ok := components.AgentRegistry.Get(agentID)
+			if !ok || agent == nil {
+				continue
+			}
+			agents[agentID] = ReflectedAgentLabels{
+				Secrecy:   tagsToStrings(agent.GetSecrecyTags()),
+				Integrity: tagsToStrings(agent.GetIntegrityTags()),
+			}
+		}
+	}
+
+	return ReflectResponse{
+		Agents:    agents,
+		Mode:      components.Mode.String(),
+		Timestamp: time.Now().UTC().Format(time.RFC3339),
+	}
+}
+
+func tagsToStrings(tags []Tag) []string {
+	out := make([]string, len(tags))
+	for i, tag := range tags {
+		out[i] = string(tag)
+	}
+	sort.Strings(out)
+	return out
+}

internal/difc/reflect_test.go

@@ -0,0 +1,34 @@
+package difc
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBuildReflectResponse_EmptyRegistry(t *testing.T) {
+	resp := BuildReflectResponse(DIFCComponents{
+		Mode:          EnforcementFilter,
+		AgentRegistry: NewAgentRegistry(),
+	})
+
+	require.NotNil(t, resp.Agents)
+	assert.Empty(t, resp.Agents)
+	assert.Equal(t, "filter", resp.Mode)
+	_, err := time.Parse(time.RFC3339, resp.Timestamp)
+	assert.NoError(t, err)
+}
+
+func TestBuildReflectResponse_SkipsNilAgentEntries(t *testing.T) {
+	reg := NewAgentRegistry()
+	reg.agents["broken"] = nil
+
+	resp := BuildReflectResponse(DIFCComponents{
+		Mode:          EnforcementStrict,
+		AgentRegistry: reg,
+	})
+
+	assert.NotContains(t, resp.Agents, "broken")
+}

internal/proxy/handler.go

@@ -53,6 +53,12 @@ func (h *proxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// Reflect endpoint exposes a live DIFC label snapshot.
+	if r.Method == http.MethodGet && rawPath == "/reflect" {
+		httputil.WriteJSONResponse(w, http.StatusOK, difc.BuildReflectResponse(h.server.DIFCComponents))
+		return
+	}
+
 	// gh CLI probes /meta during initialization for feature detection.
 	// Treat it like GraphQL introspection metadata and pass through unfiltered.
 	if r.Method == http.MethodGet && rawPath == "/meta" {

internal/proxy/handler_test.go

@@ -8,6 +8,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"testing"
+	"time"
 
 	"github.com/github/gh-aw-mcpg/internal/difc"
 	"github.com/github/gh-aw-mcpg/internal/guard"
@@ -171,6 +172,43 @@ func TestServeHTTP_GHHostPrefixStripped(t *testing.T) {
 	assert.Equal(t, "ok", got["status"])
 }
 
+func TestServeHTTP_ReflectReturnsAllAgents(t *testing.T) {
+	tests := []struct {
+		name string
+		path string
+	}{
+		{name: "/reflect", path: "/reflect"},
+		{name: "/api/v3/reflect", path: "/api/v3/reflect"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			s := newTestServer(t, "http://unused")
+			s.Mode = difc.EnforcementPropagate
+			s.AgentRegistry.Register("proxy", []difc.Tag{"repo:github/private-repo"}, []difc.Tag{"approved"})
+			s.AgentRegistry.Register("abc123def456", nil, []difc.Tag{"unapproved"})
+
+			h := &proxyHandler{server: s}
+			req := httptest.NewRequest(http.MethodGet, tt.path, nil)
+			w := httptest.NewRecorder()
+			h.ServeHTTP(w, req)
+
+			require.Equal(t, http.StatusOK, w.Code)
+			require.Equal(t, "application/json", w.Header().Get("Content-Type"))
+
+			var got difc.ReflectResponse
+			require.NoError(t, json.NewDecoder(w.Body).Decode(&got))
+			assert.Equal(t, "propagate", got.Mode)
+			assert.ElementsMatch(t, []string{"repo:github/private-repo"}, got.Agents["proxy"].Secrecy)
+			assert.ElementsMatch(t, []string{"approved"}, got.Agents["proxy"].Integrity)
+			assert.Empty(t, got.Agents["abc123def456"].Secrecy)
+			assert.ElementsMatch(t, []string{"unapproved"}, got.Agents["abc123def456"].Integrity)
+			_, err := time.Parse(time.RFC3339, got.Timestamp)
+			assert.NoError(t, err)
+		})
+	}
+}
+
 // ─── ServeHTTP: unknown GraphQL query is blocked ─────────────────────────────
 
 func TestServeHTTP_UnknownGraphQLBlocked(t *testing.T) {

internal/server/handlers.go

@@ -112,6 +112,10 @@ func registerCommonEndpoints(mux *http.ServeMux, unifiedServer *UnifiedServer, a
 	healthHandler := HandleHealth(unifiedServer)
 	mux.Handle("/health", withResponseLogging(healthHandler))
 
+	// Reflect endpoint exposes a live DIFC label snapshot.
+	reflectHandler := HandleReflect(unifiedServer)
+	mux.Handle("/reflect", withResponseLogging(reflectHandler))
+
 	// Close endpoint for graceful shutdown (spec 5.1.3)
 	closeHandler := handleClose(unifiedServer)
 	finalCloseHandler := applyAuthIfConfigured(apiKey, closeHandler.ServeHTTP)

internal/server/reflect.go

@@ -0,0 +1,15 @@
+package server
+
+import (
+	"net/http"
+
+	"github.com/github/gh-aw-mcpg/internal/difc"
+	"github.com/github/gh-aw-mcpg/internal/httputil"
+)
+
+// HandleReflect returns an http.HandlerFunc that handles the /reflect endpoint.
+func HandleReflect(unifiedServer *UnifiedServer) http.HandlerFunc {
+	return func(w http.ResponseWriter, _ *http.Request) {
+		httputil.WriteJSONResponse(w, http.StatusOK, difc.BuildReflectResponse(unifiedServer.DIFCComponents))
+	}
+}

internal/server/reflect_test.go

@@ -0,0 +1,72 @@
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/github/gh-aw-mcpg/internal/config"
+	"github.com/github/gh-aw-mcpg/internal/difc"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestReflectEndpoint_BothModes_NoAuthRequired(t *testing.T) {
+	tests := []struct {
+		name         string
+		createServer func(addr string, us *UnifiedServer, apiKey, hmacSecret string) *http.Server
+	}{
+		{name: "routed mode", createServer: CreateHTTPServerForRoutedMode},
+		{name: "gateway mode", createServer: CreateHTTPServerForMCP},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			us, err := NewUnified(context.Background(), &config.Config{Servers: map[string]*config.ServerConfig{}})
+			require.NoError(t, err)
+			t.Cleanup(func() { us.Close() })
+
+			us.AgentRegistry.Register("proxy", []difc.Tag{"repo:github/private-repo"}, []difc.Tag{"approved"})
+			us.AgentRegistry.Register("abc123def456", nil, []difc.Tag{"unapproved"})
+
+			httpServer := tt.createServer(":0", us, "test-api-key", "")
+			req := httptest.NewRequest(http.MethodGet, "/reflect", nil)
+			w := httptest.NewRecorder()
+
+			httpServer.Handler.ServeHTTP(w, req)
+
+			require.Equal(t, http.StatusOK, w.Code)
+			require.Equal(t, "application/json", w.Header().Get("Content-Type"))
+
+			var got difc.ReflectResponse
+			require.NoError(t, json.NewDecoder(w.Body).Decode(&got))
+			assert.Equal(t, us.Mode.String(), got.Mode)
+			assert.ElementsMatch(t, []string{"repo:github/private-repo"}, got.Agents["proxy"].Secrecy)
+			assert.ElementsMatch(t, []string{"approved"}, got.Agents["proxy"].Integrity)
+			assert.Empty(t, got.Agents["abc123def456"].Secrecy)
+			assert.ElementsMatch(t, []string{"unapproved"}, got.Agents["abc123def456"].Integrity)
+			_, err = time.Parse(time.RFC3339, got.Timestamp)
+			assert.NoError(t, err)
+		})
+	}
+}
+
+func TestReflectEndpoint_EmptyRegistry(t *testing.T) {
+	us, err := NewUnified(context.Background(), &config.Config{Servers: map[string]*config.ServerConfig{}})
+	require.NoError(t, err)
+	t.Cleanup(func() { us.Close() })
+
+	httpServer := CreateHTTPServerForMCP(":0", us, "", "")
+	req := httptest.NewRequest(http.MethodGet, "/reflect", nil)
+	w := httptest.NewRecorder()
+	httpServer.Handler.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code)
+
+	var got difc.ReflectResponse
+	require.NoError(t, json.NewDecoder(w.Body).Decode(&got))
+	assert.Empty(t, got.Agents)
+}