Include EDIT_SCOPE for initial setup.

includes/Modules/Analytics_4.php

@@ -93,6 +93,7 @@
 use Google\Site_Kit\Core\REST_API\REST_Routes;
 use Google\Site_Kit\Core\Tracking\Feature_Metrics_Trait;
 use Google\Site_Kit\Core\Tracking\Provides_Feature_Metrics;
+use Google\Site_Kit\Core\Util\Feature_Flags;
 use Google\Site_Kit\Modules\Analytics_4\Audience_Settings;
 use Google\Site_Kit\Modules\Analytics_4\Conversion_Reporting\Conversion_Reporting_Cron;
 use Google\Site_Kit\Modules\Analytics_4\Conversion_Reporting\Conversion_Reporting_Events_Sync;
@@ -374,10 +375,14 @@ function ( array $scopes ) {
 
 				$needs_tagmanager_scope = false;
 
+				$refined_scopes = $this->get_refined_scopes( $scopes );
+
 				if ( $oauth_client->has_sufficient_scopes(
-					array(
-						self::READONLY_SCOPE,
-						'https://www.googleapis.com/auth/tagmanager.readonly',
+					array_merge(
+						$refined_scopes,
+						array(
+							'https://www.googleapis.com/auth/tagmanager.readonly',
+						),
 					)
 				) ) {
 					$needs_tagmanager_scope = true;
@@ -387,18 +392,16 @@ function ( array $scopes ) {
 					// Unsatisfied Scopes notification to be displayed without the Additional Permissions Required
 					// modal also appearing.
 				} elseif ( ! $oauth_client->has_sufficient_scopes(
-					array(
-						self::READONLY_SCOPE,
-					)
+					$refined_scopes
 				) ) {
 					$needs_tagmanager_scope = true;
 				}
 
 				if ( $needs_tagmanager_scope ) {
-					$scopes[] = 'https://www.googleapis.com/auth/tagmanager.readonly';
+					$refined_scopes[] = 'https://www.googleapis.com/auth/tagmanager.readonly';
 				}
 
-				return $scopes;
+				return $refined_scopes;
 			}
 		);
 
@@ -2694,6 +2697,39 @@ private function get_inline_conversion_reporting_events_detection() {
 		);
 	}
 
+	/**
+	 * Refines the requested scopes based on the current authentication and connection state.
+	 *
+	 * Specifically, the `EDIT_SCOPE` is only added if the user is not yet authenticated,
+	 * or if they are authenticated and have already granted the scope, or if the module
+	 * is not yet connected (i.e. during setup).
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @param string[] $scopes Array of requested scopes.
+	 * @return string[] Refined array of requested scopes.
+	 */
+	private function get_refined_scopes( $scopes = array() ) {
+		if ( ! Feature_Flags::enabled( 'setupFlowRefresh' ) ) {
+			return $scopes;
+		}
+
+		if ( ! $this->authentication->is_authenticated() ) {
+			$scopes[] = self::EDIT_SCOPE;
+			return $scopes;
+		}
+
+		$oauth_client        = $this->authentication->get_oauth_client();
+		$granted_scopes      = $oauth_client->get_granted_scopes();
+		$is_in_setup_process = ! $this->is_connected();
+
+		if ( in_array( self::EDIT_SCOPE, $granted_scopes, true ) || $is_in_setup_process ) {
+			$scopes[] = self::EDIT_SCOPE;
+		}
+
+		return $scopes;
+	}
+
 	/**
 	 * Gets required inline data for the module.
 	 *

tests/phpunit/integration/Modules/Analytics_4Test.php

@@ -1116,6 +1116,108 @@ public function data_scopes() {
 		);
 	}
 
+	/**
+	 * @dataProvider data_scope_with_setupRefreshFlow_enabled
+	 */
+	public function test_auth_scopes_with_setupRefreshFlow( array $granted_scopes, $is_authenticated, $is_connected, array $expected_scopes ) {
+		$this->enable_feature( 'setupFlowRefresh' );
+		remove_all_filters( 'googlesitekit_auth_scopes' );
+
+		$this->analytics->register();
+
+		// Configure authentication state.
+		if ( $is_authenticated ) {
+			$this->authentication->token()->set( array( 'access_token' => 'test-access-token' ) );
+		} else {
+			$this->authentication->token()->delete();
+		}
+
+		// Configure connection state if requested.
+		if ( $is_connected ) {
+			$this->analytics->get_settings()->merge(
+				array(
+					'accountID'       => '12345678',
+					'propertyID'      => '87654321',
+					'webDataStreamID' => '1234567890',
+					'measurementID'   => 'A1B2C3D4E5',
+				)
+			);
+		}
+
+		$this->authentication->get_oauth_client()->set_granted_scopes( $granted_scopes );
+
+		$this->assertEqualSets(
+			$expected_scopes,
+			apply_filters( 'googlesitekit_auth_scopes', array() ),
+			'Auth scopes should match expected scopes based on granted scopes, authentication and connection state when setupFlowRefresh feature is enabled.'
+		);
+	}
+
+	public function data_scope_with_setupRefreshFlow_enabled() {
+		return array(
+			'unauthenticated: analytics + tag manager granted' => array(
+				array( Analytics_4::READONLY_SCOPE, 'https://www.googleapis.com/auth/tagmanager.readonly' ),
+				false,
+				false,
+				array( Analytics_4::READONLY_SCOPE, Analytics_4::EDIT_SCOPE, 'https://www.googleapis.com/auth/tagmanager.readonly' ),
+			),
+			'unauthenticated: analytics granted'         => array(
+				array( Analytics_4::READONLY_SCOPE ),
+				false,
+				false,
+				array( Analytics_4::READONLY_SCOPE, Analytics_4::EDIT_SCOPE, 'https://www.googleapis.com/auth/tagmanager.readonly' ),
+			),
+			'unauthenticated: no scopes granted'         => array(
+				array(),
+				false,
+				false,
+				array( Analytics_4::READONLY_SCOPE, Analytics_4::EDIT_SCOPE, 'https://www.googleapis.com/auth/tagmanager.readonly' ),
+			),
+			'authenticated not connected: analytics + tag manager granted' => array(
+				array( Analytics_4::READONLY_SCOPE, 'https://www.googleapis.com/auth/tagmanager.readonly' ),
+				true,
+				false,
+				array( Analytics_4::READONLY_SCOPE, Analytics_4::EDIT_SCOPE, 'https://www.googleapis.com/auth/tagmanager.readonly' ),
+			),
+			'authenticated not connected: analytics granted' => array(
+				array( Analytics_4::READONLY_SCOPE ),
+				true,
+				false,
+				array( Analytics_4::READONLY_SCOPE, Analytics_4::EDIT_SCOPE, 'https://www.googleapis.com/auth/tagmanager.readonly' ),
+			),
+			'authenticated not connected: no scopes granted' => array(
+				array(),
+				true,
+				false,
+				array( Analytics_4::READONLY_SCOPE, Analytics_4::EDIT_SCOPE, 'https://www.googleapis.com/auth/tagmanager.readonly' ),
+			),
+			'authenticated connected: analytics + tag manager granted (no edit granted)' => array(
+				array( Analytics_4::READONLY_SCOPE, 'https://www.googleapis.com/auth/tagmanager.readonly' ),
+				true,
+				true,
+				array( Analytics_4::READONLY_SCOPE, 'https://www.googleapis.com/auth/tagmanager.readonly' ),
+			),
+			'authenticated connected: analytics granted (no tagmanager)' => array(
+				array( Analytics_4::READONLY_SCOPE ),
+				true,
+				true,
+				array( Analytics_4::READONLY_SCOPE ),
+			),
+			'authenticated connected: no scopes granted' => array(
+				array(),
+				true,
+				true,
+				array( Analytics_4::READONLY_SCOPE, 'https://www.googleapis.com/auth/tagmanager.readonly' ),
+			),
+			'authenticated connected: edit + analytics granted (no tagmanager)' => array(
+				array( Analytics_4::READONLY_SCOPE, Analytics_4::EDIT_SCOPE ),
+				true,
+				true,
+				array( Analytics_4::READONLY_SCOPE, Analytics_4::EDIT_SCOPE ),
+			),
+		);
+	}
+
 	public function test_is_connected() {
 		$options   = new Options( $this->context );
 		$analytics = new Analytics_4( $this->context, $options );