feat(core): implement path validation and traversal checks in HttpCommand (googleapis#27476)

Validate and encode Discovery path parameters in `HttpCommand` to protect REST clients from path traversal and query injection, following the cross-language REST URI special characters design.

Summary of Changes
- Rejects values that are exactly `.` or `..` in simple path variables (`{var}`).
- Rejects segments that are exactly `.` or `..` in reserved path variables (`{+var}`).
- Percent-encodes reserved path variables: every character except `[-_.~0-9a-zA-Z]` and the `/` segment separator (step 4 of the design). For example `?` becomes `%3F` and `:` becomes `%3A`.
- Raises `Google::Apis::ClientError` when validation fails.

How encoding works with Addressable
`Addressable::Template` leaves reserved characters literal in `{+var}`, so `HttpCommand` encodes each reserved value before expansion and places it in the template's literal text, which Addressable passes through unchanged. Simple variables keep Addressable's encoding, which already percent-encodes every reserved character (`?` becomes `%3F`, `/` becomes `%2F`). Unicode normalization still follows `normalize_unicode`.

Deviations from the design
- **Simple variables:** The design recommends rejecting `/` in single-segment variables (step 1). This PR accepts it instead, because Addressable encodes `/` as `%2F`, which keeps the value in one path segment. Some APIs depend on this (for example Cloud Storage object names in `b/{bucket}/o/{object}`, where the object `folder/file.txt` expands to `b/my-bucket/o/folder%2Ffile.txt`).

Author: quartzmo

google-apis-core/lib/google/apis/core/http_command.rb

@@ -160,14 +160,18 @@ def authorization_refreshable?
         #
         # @private
         # @return [void]
+        # @raise [Google::Apis::ClientError] If path parameter validation fails.
         def prepare!
           normalize_unicode = true
           if options
             header.update(options.header) if options.header
             query.update(options.query) if options.query
             normalize_unicode = options.normalize_unicode
           end
-          self.url = url.expand(params, nil, normalize_unicode) if url.is_a?(Addressable::Template)
+          if url.is_a?(Addressable::Template)
+            validate_path_parameters!
+            self.url = encode_reserved_parameters(url, normalize_unicode).expand(params, nil, normalize_unicode)
+          end
           url.query_values = normalize_query_values(query).merge(url.query_values || {})
 
           if allow_form_encoding?
@@ -355,6 +359,10 @@ def set_api_version_header(api_version)
           'Google::Apis::SecretmanagerV1beta1::SecretPayload'
         ].freeze
 
+        # Matches the two URI template expressions Discovery documents use: simple ({var})
+        # and reserved ({+var}). Group 1 is '+' for reserved expansion, group 2 the name.
+        TEMPLATE_VAR_PATTERN = /\{(\+?)(\w+)\}/.freeze
+
         module RedactingPPMethods
           def pp_object(obj)
             return super unless UNSAFE_CLASS_NAMES.include? obj.class.name
@@ -479,6 +487,96 @@ def normalize_query_value(v)
             v.to_s
           end
         end
+
+        # Validates user-supplied path parameter values against the URL template specification
+        # to prevent directory traversal and parameter injection exploits.
+        #
+        # Validation rejects only dot segments. Other characters are percent-encoded instead.
+        #
+        # Validation Mechanism:
+        # 1. For simple variables ({var}, standard single-wildcard behavior):
+        #    - Rejects if the value is exactly '.' or '..'.
+        #    - Reserved characters such as '/', '?' and '#' are percent-encoded by Addressable.
+        # 2. For reserved variables ({+var}, double-wildcard behavior):
+        #    - Splits the value by slash ('/') and rejects any segment that is exactly '.' or '..'.
+        #    - Every character except '/' and unreserved characters is percent-encoded by
+        #      #encode_reserved_parameters.
+        #
+        # @raise [Google::Apis::ClientError] If any validation check fails.
+        def validate_path_parameters!
+          template_pattern = url.pattern
+
+          variables = template_pattern.scan(TEMPLATE_VAR_PATTERN).map do |operator, var_name|
+            { name: var_name, reserved: operator == '+' }
+          end
+
+          variables.each do |v|
+            var_name = v[:name]
+            var_key = params.key?(var_name) ? var_name : var_name.to_sym
+            next unless params.key?(var_key)
+
+            value = params[var_key].to_s
+
+            if v[:reserved]
+              value.split('/').each do |seg|
+                if ['.', '..'].include?(seg)
+                  raise Google::Apis::ClientError,
+                        "Value for #{var_name} must not contain segments that are exactly '#{seg}'."
+                end
+              end
+            elsif ['.', '..'].include?(value)
+              raise Google::Apis::ClientError,
+                    "Invalid value for #{var_name} '#{value}'."
+            end
+          end
+        end
+
+        # Substitutes percent-encoded values for reserved ({+var}) variables in the template.
+        #
+        # Addressable leaves reserved characters such as '+', ':', '?' and '#' literal in a
+        # reserved expansion, so they would reach the server unencoded. Only '/' and unreserved
+        # characters should stay literal, so these values are encoded here and written into the
+        # template's literal text, which Addressable passes through untouched when it expands
+        # the rest.
+        #
+        # @param [Addressable::Template] template
+        #   The URL template.
+        # @param [Boolean] normalize_unicode
+        #   Whether to apply Unicode NFC normalization to the values.
+        # @return [Addressable::Template]
+        #   A template with reserved variables replaced by their encoded values.
+        def encode_reserved_parameters(template, normalize_unicode)
+          pattern = template.pattern.dup
+          template.pattern.scan(TEMPLATE_VAR_PATTERN).each do |operator, var_name|
+            next unless operator == '+'
+
+            var_key = params.key?(var_name) ? var_name : var_name.to_sym
+            next unless params.key?(var_key)
+
+            # The encoded value contains no braces, so the new pattern parses cleanly and the
+            # value cannot introduce a template expression of its own.
+            pattern = pattern.gsub("{+#{var_name}}", encode_reserved_value(params[var_key], normalize_unicode))
+          end
+          Addressable::Template.new(pattern)
+        end
+
+        # Percent-encodes every character except '/' and unreserved characters.
+        #
+        # @param [Object] value
+        #   The parameter value.
+        # @param [Boolean] normalize_unicode
+        #   Whether to apply Unicode NFC normalization to the value.
+        # @return [String]
+        #   The encoded value.
+        def encode_reserved_value(value, normalize_unicode)
+          value = value.to_s
+          # Addressable only normalizes values left in the mapping, so normalize here to match.
+          value = value.unicode_normalize(:nfc) if normalize_unicode
+          # Split on '/' and keep empty segments (-1), so slashes stay literal.
+          # Each segment is then fully encoded, including '%' itself (as '%25').
+          unreserved = Addressable::URI::CharacterClasses::UNRESERVED
+          value.split('/', -1).map { |segment| Addressable::URI.encode_component(segment, unreserved) }.join('/')
+        end
       end
     end
   end

google-apis-core/spec/google/apis/core/http_command_spec.rb

@@ -627,4 +627,169 @@ class SecretPayload
     end
   end
 
+  describe 'path parameter validation' do
+    # Runs the command against a stub and returns the path that went out on the wire.
+    # WebMock treats '+' and '%2B' as equal, so the assertions check the expanded URL instead.
+    def wire_path(command)
+      stub_request(:get, /www\.googleapis\.com/).to_return(status: [200, ''])
+      command.options.retries = 0
+      command.execute(client)
+      command.url.path
+    end
+
+    context 'with simple path variables' do
+      # Source template specification:
+      # Pattern: v1/projects/{project}/locations/{location}/webhooks/{webhook}
+      # Variable constraints (RFC 6570 simple expansion):
+      # - Must not be exactly a traversal segment ('.', '..')
+      # - Reserved characters such as '/', '?' and '#' are percent-encoded by Addressable
+      let(:template) do
+        Addressable::Template.new(
+          'https://www.googleapis.com/v1/projects/{project}/locations/{location}/webhooks/{webhook}'
+        )
+      end
+
+      def webhook_command(webhook)
+        command = Google::Apis::Core::HttpCommand.new(:get, template)
+        command.params[:project] = 'sys-prod-123'
+        command.params[:location] = 'us-central1'
+        command.params[:webhook] = webhook
+        command
+      end
+
+      it 'should allow safe parameter values' do
+        expect(wire_path(webhook_command('billing-webhook')))
+          .to eq('/v1/projects/sys-prod-123/locations/us-central1/webhooks/billing-webhook')
+      end
+
+      it 'should percent-encode slashes in simple parameters on the wire' do
+        expect(wire_path(webhook_command('parent/child-webhook')))
+          .to eq('/v1/projects/sys-prod-123/locations/us-central1/webhooks/parent%2Fchild-webhook')
+      end
+
+      it 'should percent-encode slashes in Cloud Storage object names on the wire' do
+        storage_template = Addressable::Template.new('https://www.googleapis.com/storage/v1/b/{bucket}/o/{object}')
+        command = Google::Apis::Core::HttpCommand.new(:get, storage_template)
+        command.params[:bucket] = 'bk'
+        command.params[:object] = 'folder/file.txt'
+        expect(wire_path(command)).to eq('/storage/v1/b/bk/o/folder%2Ffile.txt')
+      end
+
+      it 'should reject dot or double-dot in simple parameters' do
+        command = webhook_command('..')
+        command.options.retries = 0
+        expect { command.execute(client) }.to raise_error(Google::Apis::ClientError, "Invalid value for webhook '..'.")
+      end
+
+      it 'should percent-encode percent signs in simple parameters on the wire' do
+        expect(wire_path(webhook_command('%2e%2e')))
+          .to eq('/v1/projects/sys-prod-123/locations/us-central1/webhooks/%252e%252e')
+        expect(wire_path(webhook_command('%2e')))
+          .to eq('/v1/projects/sys-prod-123/locations/us-central1/webhooks/%252e')
+      end
+
+      it 'should percent-encode query and fragment characters in simple parameters on the wire' do
+        expect(wire_path(webhook_command('billing-webhook?key=val')))
+          .to eq('/v1/projects/sys-prod-123/locations/us-central1/webhooks/billing-webhook%3Fkey%3Dval')
+        expect(wire_path(webhook_command('billing-webhook#fragment')))
+          .to eq('/v1/projects/sys-prod-123/locations/us-central1/webhooks/billing-webhook%23fragment')
+      end
+    end
+
+    context 'with reserved path variables' do
+      # Source template specification:
+      # Pattern: v1/{+parent}/indexes
+      # Variable constraints (RFC 6570 reserved expansion):
+      # - Allows slashes (multiple path segments), including empty segments
+      # - Must not contain traversal segments ('.', '..')
+      # - Every character except '/' and unreserved characters is percent-encoded
+      let(:template) { Addressable::Template.new('https://www.googleapis.com/v1/{+parent}/indexes') }
+
+      def parent_command(parent)
+        command = Google::Apis::Core::HttpCommand.new(:get, template)
+        command.params[:parent] = parent
+        command
+      end
+
+      def expect_rejected(parent, message)
+        command = parent_command(parent)
+        command.options.retries = 0
+        expect { command.execute(client) }.to raise_error(Google::Apis::ClientError, message)
+      end
+
+      it 'should allow safe double wildcard paths' do
+        expect(wire_path(parent_command('projects/sys-prod-123/databases/default/documents/doc-1')))
+          .to eq('/v1/projects/sys-prod-123/databases/default/documents/doc-1/indexes')
+      end
+
+      it 'should percent-encode query characters in reserved parameters' do
+        expect(wire_path(parent_command('projects/sys-prod-123?key=val')))
+          .to eq('/v1/projects/sys-prod-123%3Fkey%3Dval/indexes')
+      end
+
+      it 'should percent-encode fragment characters in reserved parameters' do
+        expect(wire_path(parent_command('projects/sys-prod-123#fragment')))
+          .to eq('/v1/projects/sys-prod-123%23fragment/indexes')
+      end
+
+      it 'should percent-encode colons in reserved parameters' do
+        expect(wire_path(parent_command('projects/p:undelete'))).to eq('/v1/projects/p%3Aundelete/indexes')
+      end
+
+      it 'should percent-encode other reserved characters in reserved parameters' do
+        expect(wire_path(parent_command('projects/p/topics/a+b@c,d=e')))
+          .to eq('/v1/projects/p/topics/a%2Bb%40c%2Cd%3De/indexes')
+      end
+
+      it 'should percent-encode braces in reserved parameters' do
+        expect(wire_path(parent_command('projects/{x}'))).to eq('/v1/projects/%7Bx%7D/indexes')
+      end
+
+      it 'should not normalize unicode in reserved parameters by default' do
+        expect(wire_path(parent_command("projects/Cafe\u0301"))).to eq('/v1/projects/Cafe%CC%81/indexes')
+      end
+
+      it 'should normalize unicode in reserved parameters when requested' do
+        command = parent_command("projects/Cafe\u0301")
+        command.options.normalize_unicode = true
+        expect(wire_path(command)).to eq('/v1/projects/Caf%C3%A9/indexes')
+      end
+
+      it 'should reject relative traversals inside the wildcard' do
+        expect_rejected('projects/sys-prod-123/databases/default/documents/doc-1/../../default',
+                        "Value for parent must not contain segments that are exactly '..'.")
+      end
+
+      it 'should reject traversals escaping the left parameter boundary' do
+        expect_rejected('projects/sys-prod-123/databases/default/documents/doc-1/../../../../../../../escape-db',
+                        "Value for parent must not contain segments that are exactly '..'.")
+      end
+
+      it 'should reject parameter values starting with parent directory traversals' do
+        expect_rejected('../escape-db', "Value for parent must not contain segments that are exactly '..'.")
+      end
+
+      it 'should reject invalid segments like single dot' do
+        expect_rejected('projects/sys-prod-123/./databases/default',
+                        "Value for parent must not contain segments that are exactly '.'.")
+      end
+
+      it 'should percent-encode percent signs in reserved parameters on the wire' do
+        expect(wire_path(parent_command('projects/p/databases/d/documents/doc/%2e%2e/doc2')))
+          .to eq('/v1/projects/p/databases/d/documents/doc/%252e%252e/doc2/indexes')
+        expect(wire_path(parent_command('projects/p/databases/d/documents/doc/%2e/a')))
+          .to eq('/v1/projects/p/databases/d/documents/doc/%252e/a/indexes')
+        expect(wire_path(parent_command('projects/p/databases/d/documents/doc/..%2f..%2fescape-db')))
+          .to eq('/v1/projects/p/databases/d/documents/doc/..%252f..%252fescape-db/indexes')
+        expect(wire_path(parent_command('projects/p/databases/d/documents/doc/%2e%2e%2f%2e%2e%2fescape-db')))
+          .to eq('/v1/projects/p/databases/d/documents/doc/%252e%252e%252f%252e%252e%252fescape-db/indexes')
+      end
+
+      it 'should allow empty segments in reserved parameters' do
+        expect(wire_path(parent_command('projects/sys-prod-123//databases/default')))
+          .to eq('/v1/projects/sys-prod-123//databases/default/indexes')
+        expect(wire_path(parent_command('projects/sys-prod-123/'))).to eq('/v1/projects/sys-prod-123//indexes')
+      end
+    end
+  end
 end