feat(mcp): add API key tools

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9ff1e38a-b018-4cf7-a5e9-5044a2efd03c
NdoleStudio · AchoArnold · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026
commit a13bc7d431702ff685dbaac1d4f8aed74fc1b35e
diff --git a/mcp/internal/auth/middleware.go b/mcp/internal/auth/middleware.go
@@ -87,6 +87,22 @@ func PrincipalFromContext(ctx context.Context) (Principal, bool) {
 	return principal, ok
 }
 
+// ClientIDFromContext returns the OAuth client ID carried by the MCP access
+// token that mcpauth.RequireBearerToken (configured with a Verifier's
+// VerifyMCPToken) has already validated for the current request, or false
+// if ctx carries no verified token. Tools use this to bind sensitive
+// confirmation state (see the rotate_user_api_key tool) to the exact OAuth
+// client that requested the operation, not just the authenticated user.
+func ClientIDFromContext(ctx context.Context) (string, bool) {
+	info := mcpauth.TokenInfoFromContext(ctx)
+	if info == nil {
+		return "", false
+	}
+
+	clientID, ok := info.Extra[tokenInfoClientIDKey].(string)
+	return clientID, ok
+}
+
 // RequireScope returns the Principal carried by ctx's already-validated MCP
 // access token, or an error if ctx carries no verified token or the token's
 // scopes do not include scope. It never calls the httpSMS API and never

diff --git a/mcp/internal/auth/middleware_test.go b/mcp/internal/auth/middleware_test.go
@@ -36,8 +36,12 @@ func newMiddlewareTestServer(t *testing.T, keys *auth.KeySet, requiredScopes []s
 		principal, ok := auth.PrincipalFromContext(r.Context())
 		require.True(t, ok, "auth.PrincipalFromContext must find the principal the middleware stored")
 
+		clientID, ok := auth.ClientIDFromContext(r.Context())
+		require.True(t, ok, "auth.ClientIDFromContext must find the client ID the middleware stored")
+
 		w.Header().Set("X-Test-User-ID", info.UserID)
 		w.Header().Set("X-Test-Principal-Email", principal.Email)
+		w.Header().Set("X-Test-Client-ID", clientID)
 		w.WriteHeader(http.StatusOK)
 	})
 
@@ -145,6 +149,7 @@ func TestRequireBearerTokenAcceptsValidTokenAndStoresTokenInfo(t *testing.T) {
 	require.Equal(t, http.StatusOK, resp.StatusCode)
 	assert.Equal(t, testFirebaseUserID, resp.Header.Get("X-Test-User-ID"))
 	assert.Equal(t, testUserEmail, resp.Header.Get("X-Test-Principal-Email"))
+	assert.Equal(t, "client", resp.Header.Get("X-Test-Client-ID"))
 }
 
 func doBearerRequest(t *testing.T, url string, token string) *http.Response {
@@ -164,6 +169,11 @@ func TestPrincipalFromContextReturnsFalseWithoutToken(t *testing.T) {
 	assert.False(t, ok)
 }
 
+func TestClientIDFromContextReturnsFalseWithoutToken(t *testing.T) {
+	_, ok := auth.ClientIDFromContext(t.Context())
+	assert.False(t, ok)
+}
+
 func TestRequireScopeReturnsErrorWithoutToken(t *testing.T) {
 	_, err := auth.RequireScope(t.Context(), auth.ScopePhonesRead)
 	require.Error(t, err)

diff --git a/mcp/internal/oauth/store.go b/mcp/internal/oauth/store.go
@@ -326,6 +326,21 @@ func (s *RedisStore) ConsumeConfirmation(ctx context.Context, handle string) (Co
 	return record, err
 }
 
+// confirmationHandleBytes is the amount of crypto/rand entropy (see
+// newRandomToken) encoded into a rotation confirmation handle.
+const confirmationHandleBytes = 32
+
+// NewConfirmationHandle returns a new cryptographically random, one-time
+// confirmation handle for the primary-API-key-rotation confirmation flow
+// (see Confirmation, PutConfirmation, and ConsumeConfirmation). Callers
+// store it with PutConfirmation and hand it to the client -- as
+// mcp.CallToolResult.RequestState for MRTR-capable clients, or as plain
+// tool output text for legacy clients that must echo it back explicitly --
+// and later redeem it exactly once with ConsumeConfirmation.
+func NewConfirmationHandle() (string, error) {
+	return newRandomToken(confirmationHandleBytes)
+}
+
 // hashedKey returns the namespaced Redis key for publicValue under prefix:
 // prefix followed by the hex-encoded SHA-256 hash of publicValue. The raw
 // value is never used as key material.

diff --git a/mcp/internal/oauth/store_test.go b/mcp/internal/oauth/store_test.go
@@ -267,6 +267,31 @@ func TestRedisStoreGetDynamicClientNotFound(t *testing.T) {
 	require.ErrorIs(t, err, oauth.ErrNotFound)
 }
 
+// TestNewConfirmationHandleIsRandomAndURLSafe asserts NewConfirmationHandle
+// returns a fresh, non-empty, URL-safe value on every call (never a fixed
+// or predictable value), and that the handle it returns actually works
+// end-to-end with PutConfirmation/ConsumeConfirmation.
+func TestNewConfirmationHandleIsRandomAndURLSafe(t *testing.T) {
+	first, err := oauth.NewConfirmationHandle()
+	require.NoError(t, err)
+	assert.NotEmpty(t, first)
+	assert.NotRegexp(t, `[^A-Za-z0-9_-]`, first, "confirmation handle must be URL-safe base64")
+
+	second, err := oauth.NewConfirmationHandle()
+	require.NoError(t, err)
+	assert.NotEqual(t, first, second, "two generated handles must never collide")
+
+	store, _ := newTestStore(t)
+	ctx := context.Background()
+
+	confirmation := oauth.Confirmation{Handle: first, UserID: "firebase-uid", ClientID: "client-id", Operation: "rotate_user_api_key"}
+	require.NoError(t, store.PutConfirmation(ctx, confirmation, time.Minute))
+
+	got, err := store.ConsumeConfirmation(ctx, first)
+	require.NoError(t, err)
+	assert.Equal(t, confirmation.UserID, got.UserID)
+}
+
 func TestRedisStoreConsumeConfirmationIsOneTimeUse(t *testing.T) {
 	store, _ := newTestStore(t)
 	ctx := context.Background()