feat: implement OAuth Client ID Metadata Document (#1525) (#1526)

Co-authored-by: Elias Schneider <login@eliasschneider.com>

backend/internal/middleware/client_id_param.go

@@ -0,0 +1,56 @@
+package middleware
+
+import (
+	"encoding/base64"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+// clientIDParamPrefix marks a path parameter whose value is a base64url-encoded
+// client ID. CIMD client IDs are full https URLs, so they contain slashes and
+// colons that cannot be carried in a single path segment. The frontend encodes
+// such IDs as "~<base64url>"; this middleware decodes them back before
+// handlers read c.Param.
+//
+// The prefix "~" is unreserved in RFC 3986 (so proxies leave it intact) and never
+// appears in raw pocket-id client IDs ([a-zA-Z0-9._-]+) or user UUIDs, making the
+// encoding unambiguous and backward compatible: unprefixed params pass through
+// untouched, so external API consumers using plain client IDs are unaffected.
+const clientIDParamPrefix = "~"
+
+// decodedClientIDParamKeys lists the path parameter names that may carry an
+// encoded client ID.
+var decodedClientIDParamKeys = map[string]struct{}{
+	"id":       {},
+	"clientId": {},
+}
+
+// ClientIDParamMiddleware decodes "~<base64url>" client ID path parameters in
+// place. Values without the prefix, or that fail to decode, are left unchanged.
+type ClientIDParamMiddleware struct{}
+
+func NewClientIDParamMiddleware() *ClientIDParamMiddleware {
+	return &ClientIDParamMiddleware{}
+}
+
+func (m *ClientIDParamMiddleware) Add() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		for i, p := range c.Params {
+			if _, ok := decodedClientIDParamKeys[p.Key]; !ok {
+				continue
+			}
+			encoded, ok := strings.CutPrefix(p.Value, clientIDParamPrefix)
+			if !ok {
+				continue
+			}
+			decoded, err := base64.RawURLEncoding.DecodeString(encoded)
+			if err != nil {
+				continue
+			}
+			c.Params[i].Value = string(decoded)
+		}
+
+		c.Next()
+	}
+}

backend/internal/middleware/client_id_param_test.go

@@ -0,0 +1,69 @@
+package middleware
+
+import (
+	"encoding/base64"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func TestClientIDParamMiddleware(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	const cimdURL = "https://claude.ai/oauth/claude-code-client-metadata"
+	encoded := "~" + base64.RawURLEncoding.EncodeToString([]byte(cimdURL))
+
+	tests := []struct {
+		name  string
+		param string
+		want  string
+	}{
+		{"plain client ID unchanged", "my-client_id.1", "my-client_id.1"},
+		{"uuid unchanged", "550e8400-e29b-41d4-a716-446655440000", "550e8400-e29b-41d4-a716-446655440000"},
+		{"encoded CIMD URL decoded", encoded, cimdURL},
+		{"invalid base64 left as-is", "~!!!", "~!!!"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			router := gin.New()
+			router.Use(NewClientIDParamMiddleware().Add())
+
+			var got string
+			router.GET("/oidc/clients/:id/meta", func(c *gin.Context) {
+				got = c.Param("id")
+				c.Status(http.StatusOK)
+			})
+
+			req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/oidc/clients/"+tt.param+"/meta", http.NoBody)
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			require.Equal(t, http.StatusOK, w.Code)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestClientIDParamMiddlewareIgnoresNonClientParams(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	router := gin.New()
+	router.Use(NewClientIDParamMiddleware().Add())
+
+	var got string
+	// "~"-prefixed value on a non-client param key must pass through untouched.
+	router.GET("/users/:userId", func(c *gin.Context) {
+		got = c.Param("userId")
+		c.Status(http.StatusOK)
+	})
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/users/~abc", http.NoBody)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	require.Equal(t, "~abc", got)
+}