Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions errors/parameters_howtofix.go
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ const (
HowToFixMissingValue string = "Ensure the value has been set"
HowToFixPath string = "Check the path is correct, and check that the correct HTTP method has been used (e.g. GET, POST, PUT, DELETE)"
HowToFixPathMethod string = "Add the missing operation to the contract for the path"
HowToFixAmbiguousPath string = "Send the path in canonical form: do not percent-encode characters allowed in a path segment, do not encode '/', and remove empty and dot segments"
HowToFixInvalidMaxItems string = "Reduce the number of items in the array to %d or less"
HowToFixInvalidMinItems string = "Increase the number of items in the array to %d or more"
HowToFixMissingHeader string = "Make sure the service responding sets the required headers with this response code"
Expand Down
1 change: 1 addition & 0 deletions helpers/constants.go
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ const (
PathValidation = "path"
ValidationMissing = "missing"
ValidationMissingOperation = "missingOperation"
ValidationAmbiguousPath = "ambiguousPath"
ResponseBodyResponseCode = "statusCode"
SecurityValidation = "security"
DocumentValidation = "document"
Expand Down
133 changes: 133 additions & 0 deletions internal/pathvariant/pathvariant.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
// Copyright 2023-2026 Princess Beef Heavy Industries, LLC / Dave Shanley
// SPDX-License-Identifier: MIT

// Package pathvariant lists the other ways a server or router may read an escaped request path.
//
// Routers disagree on percent-encoding and path cleaning. net/http ServeMux decodes each segment
// before comparing it, gin and gorilla/mux route on the fully decoded path, chi and echo route on
// the escaped path, and some routers remove empty and dot segments. A validator that reads a path
// one way, in front of a router that reads it another, can validate one operation while the router
// runs a different one. Comparing the operation selected by each reading closes that gap.
package pathvariant

import (
"path"
"slices"
"strings"
)

// Variants returns the readings of an escaped request path that differ from the path as sent:
// with percent-encoded path characters decoded, with encoded slashes also decoded, and each of
// those with empty and dot segments removed. It returns nil when every reading is the path itself.
func Variants(escapedPath string) []string {
if !mayVary(escapedPath) {
return nil
}
decoded := decode(escapedPath, false)
split := decode(escapedPath, true)
var variants []string
for _, variant := range []string{decoded, split, clean(escapedPath), clean(decoded), clean(split)} {
if variant != escapedPath && !slices.Contains(variants, variant) {
variants = append(variants, variant)
}
}
return variants
}

// CollapseSlashes replaces each run of slashes in a path with a single slash.
func CollapseSlashes(p string) string {
var b strings.Builder
b.Grow(len(p))
for i := 0; i < len(p); i++ {
if p[i] != '/' || i == 0 || p[i-1] != '/' {
b.WriteByte(p[i])
}
}
return b.String()
}

// mayVary reports whether a path contains a percent-encoding, an empty segment, or a dot segment.
func mayVary(p string) bool {
for i := 0; i < len(p); i++ {
switch p[i] {
case '%':
return true
case '/':
if i+1 < len(p) && (p[i+1] == '/' || p[i+1] == '.') {
return true
}
}
}
return false
}

// decode decodes each percent-encoded octet that may appear unencoded in a path segment
// (RFC 3986 pchar: unreserved, sub-delims, ":" and "@") or that is part of a UTF-8 sequence.
// With slashes set it also decodes "%2F". Every other octet, including "%25", stays encoded, so
// the result is still an escaped path and is never decoded twice.
func decode(p string, slashes bool) string {
var b strings.Builder
changed := false
for i := 0; i < len(p); i++ {
if p[i] == '%' && i+2 < len(p) {
if c, ok := unhex(p[i+1], p[i+2]); ok && (pathChar(c) || (slashes && c == '/')) {
if !changed {
changed = true
b.Grow(len(p))
b.WriteString(p[:i])
}
b.WriteByte(c)
i += 2
continue
}
}
if changed {
b.WriteByte(p[i])
}
}
if !changed {
return p
}
return b.String()
}

// clean removes empty and dot segments, keeping a trailing slash, as net/http ServeMux does.
func clean(p string) string {
cleaned := path.Clean(p)
if strings.HasSuffix(p, "/") && cleaned != "/" {
cleaned += "/"
}
return cleaned
}

func pathChar(c byte) bool {
switch {
case 'a' <= c && c <= 'z', 'A' <= c && c <= 'Z', '0' <= c && c <= '9', c >= 0x80:
return true
}
return strings.IndexByte("-._~!$&'()*+,;=:@", c) >= 0
}

func unhex(hi, lo byte) (byte, bool) {
h, ok := hexValue(hi)
if !ok {
return 0, false
}
l, ok := hexValue(lo)
if !ok {
return 0, false
}
return h<<4 | l, true
}

func hexValue(c byte) (byte, bool) {
switch {
case '0' <= c && c <= '9':
return c - '0', true
case 'a' <= c && c <= 'f':
return c - 'a' + 10, true
case 'A' <= c && c <= 'F':
return c - 'A' + 10, true
}
return 0, false
}
81 changes: 81 additions & 0 deletions internal/pathvariant/pathvariant_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
// Copyright 2023-2026 Princess Beef Heavy Industries, LLC / Dave Shanley
// SPDX-License-Identifier: MIT

package pathvariant

import (
"testing"

"github.com/pb33f/testify/assert"
)

func TestVariants(t *testing.T) {
for _, tc := range []struct {
path string
expected []string
}{
// nothing to normalize
{"/users/me", nil},
{"", nil},
{"/", nil},
{"/users/me.json", nil},
// percent-encodings that decode to the same reading
{"/users/a%20b", nil},
{"/users/%25", nil},
{"/users/%zz", nil},
{"/users/%6", nil},
{"/users/%6z", nil},
{"/users/%", nil},
// a dot segment-looking name that is not one
{"/.well-known/openid", nil},
// over-encoded path characters, upper and lower case hex
{"/users/m%65", []string{"/users/me"}},
{"/users/%6D%65", []string{"/users/me"}},
{"/users/%6d%65", []string{"/users/me"}},
{"/v1/items%3Abatch", []string{"/v1/items:batch"}},
{"/a/%7E%21%24%26%27%28%29%2A%2B%2C%3B%3D%40%2D%2E%5F", []string{"/a/~!$&'()*+,;=@-._"}},
{"/caf%C3%A9", []string{"/caf\xc3\xa9"}},
// encoded characters that are not path characters stay encoded
{"/a%23b%3Fc%25d%2Fe", []string{"/a%23b%3Fc%25d/e"}},
// "%2541" is a literal "%41", never a second "A"
{"/m%2541", nil},
// encoded slashes split only in the split reading
{"/users/5%2Fsecrets", []string{"/users/5/secrets"}},
{"/users/5%2fsecrets", []string{"/users/5/secrets"}},
{"/users/m%65%2Fx", []string{"/users/me%2Fx", "/users/me/x"}},
// empty and dot segments, trailing slash kept
{"/items//5", []string{"/items/5"}},
{"/items//", []string{"/items/"}},
{"/users/x/../me", []string{"/users/me"}},
{"/users/./me/", []string{"/users/me/"}},
{"//", []string{"/"}},
{"/..", []string{"/"}},
// encoded dots and slashes become dot segments only once decoded
{"/users/%2E%2E/admin", []string{"/users/../admin", "/admin"}},
{"/a/b%2F..%2Fc", []string{"/a/b/../c", "/a/c"}},
{"/a%2F%2Fb", []string{"/a//b", "/a/b"}},
} {
assert.Equal(t, tc.expected, Variants(tc.path), tc.path)
}
}

func TestCollapseSlashes(t *testing.T) {
for path, expected := range map[string]string{
"": "",
"/": "/",
"//": "/",
"/items//5": "/items/5",
"///items///5///": "/items/5/",
"/users/a%2F%2Fb": "/users/a%2F%2Fb",
"items//5": "items/5",
} {
assert.Equal(t, expected, CollapseSlashes(path), path)
}
}

func TestDecodeKeepsPathWithoutDecodableOctets(t *testing.T) {
path := "/users/a%20b"
assert.Equal(t, path, decode(path, true))
assert.Equal(t, "/users/me", decode("/users/m%65", false))
assert.Equal(t, "e/x", decode("%65/x", false))
}
10 changes: 10 additions & 0 deletions internal/serverurl/serverurl.go
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,13 @@ func BasePath(serverURL string) string {
}
return u.Path
}

// TrimBasePath removes base from the start of path when base ends on a segment boundary, so a
// base of "/api" matches "/api" and "/api/pets" but not "/apistatus". It reports whether base matched.
func TrimBasePath(path, base string) (string, bool) {
rest, ok := strings.CutPrefix(path, base)
if !ok || (rest != "" && rest[0] != '/' && !strings.HasSuffix(base, "/")) {
return path, false
}
return rest, true
}
21 changes: 21 additions & 0 deletions internal/serverurl/serverurl_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,24 @@ func TestBasePath(t *testing.T) {
assert.Equal(t, expected, BasePath(serverURL), serverURL)
}
}

func TestTrimBasePath(t *testing.T) {
for _, tc := range []struct {
path, base, rest string
ok bool
}{
{"/api", "/api", "", true},
{"/api/", "/api", "/", true},
{"/api/status", "/api", "/status", true},
{"/apistatus", "/api", "/apistatus", false},
{"/api-v2/status", "/api", "/api-v2/status", false},
{"/other", "/api", "/other", false},
{"/api/status", "/api/", "status", true},
{"/api", "/api/", "/api", false},
{"/status", "/", "status", true},
} {
rest, ok := TrimBasePath(tc.path, tc.base)
assert.Equal(t, tc.rest, rest, "%s - %s", tc.path, tc.base)
assert.Equal(t, tc.ok, ok, "%s - %s", tc.path, tc.base)
}
}
72 changes: 64 additions & 8 deletions paths/paths.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import (
"github.com/pb33f/libopenapi-validator/config"
"github.com/pb33f/libopenapi-validator/errors"
"github.com/pb33f/libopenapi-validator/helpers"
"github.com/pb33f/libopenapi-validator/internal/pathvariant"
"github.com/pb33f/libopenapi-validator/internal/requeststate"
"github.com/pb33f/libopenapi-validator/internal/serverurl"
"github.com/pb33f/libopenapi-validator/router"
Expand All @@ -34,6 +35,10 @@ import (
//
// Path matching follows the OpenAPI specification: literal (concrete) paths take precedence over
// parameterized paths, regardless of definition order in the specification.
//
// A request path that selects a different operation when its percent-encoding, encoded slashes, or
// empty and dot segments are normalized is rejected as ambiguous, because a router could run an
// operation other than the one validated.
func FindPath(request *http.Request, document *v3.Document, options *config.ValidationOptions) (*v3.PathItem, []*errors.ValidationError, string) {
if options != nil && options.Router != nil {
route, validationErrors := ResolveRoute(request, document, options)
Expand All @@ -42,8 +47,35 @@ func FindPath(request *http.Request, document *v3.Document, options *config.Vali
}
return route.PathItem, validationErrors, route.Path
}
stripped := StripRequestPath(request, document)
pathItem, validationErrors, foundPath := findPath(request, document, options, StripRequestPath(request, document))
if requeststate.Route(request) != nil {
return pathItem, validationErrors, foundPath
}
escapedPath := request.URL.EscapedPath()
if pathItem == nil && strings.Contains(escapedPath, "//") {
// doubled slashes match as single ones when nothing matches them as sent
collapsed := stripPath(pathvariant.CollapseSlashes(escapedPath), request.URL.Fragment, getBasePaths(document))
pathItem, validationErrors, foundPath = findPath(request, document, options, collapsed)
}
if len(validationErrors) > 0 {
return pathItem, validationErrors, foundPath
}
// a router that reads the path another way must run the same operation, or the request is rejected
if variants := pathvariant.Variants(escapedPath); len(variants) > 0 {
operation := helpers.ExtractOperation(request, pathItem)
basePaths := getBasePaths(document)
for _, variant := range variants {
other, otherErrors, _ := findPath(request, document, options, stripPath(variant, request.URL.Fragment, basePaths))
if len(otherErrors) == 0 && helpers.ExtractOperation(request, other) != operation {
return nil, ambiguousPathError(request), ""
}
}
}
return pathItem, nil, foundPath
}

// findPath matches stripped, one reading of the request path without its base path.
func findPath(request *http.Request, document *v3.Document, options *config.ValidationOptions, stripped string) (*v3.PathItem, []*errors.ValidationError, string) {
// Fast path: try radix tree first (O(k) where k = path depth)
// If no path lookup is provided, we will fall back to regex-based matching.
if options != nil && options.PathTree != nil {
Expand Down Expand Up @@ -147,6 +179,9 @@ func ResolveRoute(request *http.Request, document *v3.Document, options *config.
if stderrors.Is(err, router.ErrMethodNotAllowed) && route != nil {
return route, missingOperationError(request, route.Path)
}
if stderrors.Is(err, router.ErrAmbiguousPath) {
return nil, ambiguousPathError(request)
}
validationErrors := []*errors.ValidationError{{
ValidationType: helpers.PathValidation,
ValidationSubType: helpers.ValidationMissing,
Expand Down Expand Up @@ -196,12 +231,15 @@ func StripRequestPath(request *http.Request, document *v3.Document) string {
}
return stripped
}
basePaths := getBasePaths(document)
return stripPath(request.URL.EscapedPath(), request.URL.Fragment, getBasePaths(document))
}

// strip any base path
stripped := stripBaseFromPath(request.URL.EscapedPath(), basePaths)
if request.URL.Fragment != "" {
stripped = fmt.Sprintf("%s#%s", stripped, request.URL.Fragment)
// stripPath removes the first matching base path from an escaped request path, appends the
// fragment, and makes the result absolute.
func stripPath(escapedPath, fragment string, basePaths []string) string {
stripped := stripBaseFromPath(escapedPath, basePaths)
if fragment != "" {
stripped = fmt.Sprintf("%s#%s", stripped, fragment)
}
if !strings.HasPrefix(stripped, "/") {
stripped = "/" + stripped
Expand All @@ -227,8 +265,8 @@ func checkPathAgainstBase(docPath, urlPath string, basePaths []string) bool {

func stripBaseFromPath(path string, basePaths []string) string {
for i := range basePaths {
if strings.HasPrefix(path, basePaths[i]) {
return path[len(basePaths[i]):]
if rest, ok := serverurl.TrimBasePath(path, basePaths[i]); ok {
return rest
}
}
return path
Expand Down Expand Up @@ -272,6 +310,24 @@ func comparePaths(mapped, requested, basePaths []string, regexCache config.Regex
return checkPathAgainstBase(l, r, basePaths)
}

// ambiguousPathError returns a validation error for a request path whose normalized readings select
// different operations.
func ambiguousPathError(request *http.Request) []*errors.ValidationError {
validationErrors := []*errors.ValidationError{{
ValidationType: helpers.PathValidation,
ValidationSubType: helpers.ValidationAmbiguousPath,
Message: fmt.Sprintf("%s Path '%s' is ambiguous", request.Method, request.URL.EscapedPath()),
Reason: fmt.Sprintf("The %s request path '%s' selects a different operation when its percent-encoding, "+
"encoded slashes, or empty and dot segments are normalized, so a router could run an operation "+
"other than the one validated", request.Method, request.URL.EscapedPath()),
SpecLine: -1,
SpecCol: -1,
HowToFix: errors.HowToFixAmbiguousPath,
}}
errors.PopulateValidationErrors(validationErrors, request, "")
return validationErrors
}

// missingOperationError returns a validation error for when a path was found but the HTTP method doesn't exist.
func missingOperationError(request *http.Request, matchedPath string) []*errors.ValidationError {
validationErrors := []*errors.ValidationError{{
Expand Down
Loading
Loading