diff --git a/errors/parameters_howtofix.go b/errors/parameters_howtofix.go index 143197e..785b8aa 100644 --- a/errors/parameters_howtofix.go +++ b/errors/parameters_howtofix.go @@ -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" diff --git a/helpers/constants.go b/helpers/constants.go index f1e1f3b..3477459 100644 --- a/helpers/constants.go +++ b/helpers/constants.go @@ -25,6 +25,7 @@ const ( PathValidation = "path" ValidationMissing = "missing" ValidationMissingOperation = "missingOperation" + ValidationAmbiguousPath = "ambiguousPath" ResponseBodyResponseCode = "statusCode" SecurityValidation = "security" DocumentValidation = "document" diff --git a/internal/pathvariant/pathvariant.go b/internal/pathvariant/pathvariant.go new file mode 100644 index 0000000..f3ba6b6 --- /dev/null +++ b/internal/pathvariant/pathvariant.go @@ -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 +} diff --git a/internal/pathvariant/pathvariant_test.go b/internal/pathvariant/pathvariant_test.go new file mode 100644 index 0000000..0282ca8 --- /dev/null +++ b/internal/pathvariant/pathvariant_test.go @@ -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)) +} diff --git a/internal/serverurl/serverurl.go b/internal/serverurl/serverurl.go index 6d9a20b..ab87966 100644 --- a/internal/serverurl/serverurl.go +++ b/internal/serverurl/serverurl.go @@ -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 +} diff --git a/internal/serverurl/serverurl_test.go b/internal/serverurl/serverurl_test.go index 485de59..d21d716 100644 --- a/internal/serverurl/serverurl_test.go +++ b/internal/serverurl/serverurl_test.go @@ -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) + } +} diff --git a/paths/paths.go b/paths/paths.go index ad9d8a1..7082ee7 100644 --- a/paths/paths.go +++ b/paths/paths.go @@ -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" @@ -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) @@ -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 { @@ -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, @@ -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 @@ -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 @@ -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{{ diff --git a/paths/paths_test.go b/paths/paths_test.go index 2bd6deb..9abbd22 100644 --- a/paths/paths_test.go +++ b/paths/paths_test.go @@ -13,6 +13,8 @@ import ( "github.com/pb33f/libopenapi" "github.com/pb33f/libopenapi-validator/config" + validationErrors "github.com/pb33f/libopenapi-validator/errors" + "github.com/pb33f/libopenapi-validator/helpers" "github.com/pb33f/libopenapi-validator/internal/requeststate" "github.com/pb33f/libopenapi-validator/radix" "github.com/pb33f/libopenapi-validator/router" @@ -679,6 +681,12 @@ func TestStripRequestPath(t *testing.T) { reqURL: "https://things.com/v1beta/weather", want: "/", }, + { + name: "base path that is not a whole segment is not stripped", + servers: []string{"https://things.com/api"}, + reqURL: "https://things.com/apiusers", + want: "/apiusers", + }, { name: "fragment preserved after stripping", servers: []string{"https://things.com/api"}, @@ -1692,3 +1700,100 @@ paths: assert.True(t, errs[0].IsOperationMissingError()) assert.Equal(t, "/users/{id}", foundPath) } + +const ambiguousPathSpec = `openapi: 3.1.0 +servers: [{url: https://example.com/api}] +paths: + /users/me: + get: {operationId: me} + /users/{id}: + get: {operationId: user} + /users/{id}/secrets: + get: {operationId: secrets} + /reports/latest: + put: {operationId: putLatest} + /reports/{id}: + get: {operationId: report} + /status: + get: {operationId: status} + /{id}: + get: {operationId: anything} +` + +func ambiguousPathOptions(t *testing.T) (*v3.Document, map[string]*config.ValidationOptions) { + doc, err := libopenapi.NewDocument([]byte(ambiguousPathSpec)) + assert.NoError(t, err) + m, _ := doc.BuildV3Model() + withRouter := config.NewValidationOptions() + withRouter.Router = router.NewRouter(&m.Model, router.WithPathOnlyMatching()) + return &m.Model, map[string]*config.ValidationOptions{ + "regex": nil, + "radix": config.NewValidationOptions(config.WithPathTree(radix.BuildPathTree(&m.Model))), + "router": withRouter, + } +} + +func TestFindPath_RejectsAmbiguousPaths(t *testing.T) { + doc, options := ambiguousPathOptions(t) + for name, opts := range options { + for _, target := range []string{ + "https://example.com/api/users/m%65", + "https://example.com/api/users/5%2Fsecrets", + "https://example.com/api/users/../secrets", + } { + request, _ := http.NewRequest(http.MethodGet, target, nil) + pathItem, errs, foundPath := FindPath(request, doc, opts) + assert.Nil(t, pathItem, "%s %s", name, target) + assert.Empty(t, foundPath, "%s %s", name, target) + if assert.Len(t, errs, 1, "%s %s", name, target) { + assert.Equal(t, helpers.PathValidation, errs[0].ValidationType) + assert.Equal(t, helpers.ValidationAmbiguousPath, errs[0].ValidationSubType) + assert.Equal(t, fmt.Sprintf("GET Path '%s' is ambiguous", request.URL.EscapedPath()), errs[0].Message) + assert.Equal(t, validationErrors.HowToFixAmbiguousPath, errs[0].HowToFix) + } + } + + // readings that agree, match nothing, or lack the method keep the path as sent + for target, expected := range map[string]string{ + "https://example.com/api/users/a%20b": "/users/{id}", + "https://example.com/api/users/%61lice": "/users/{id}", + "https://example.com/api/status%2Fx": "/{id}", + "https://example.com/api/reports/l%61test": "/reports/{id}", + "https://example.com/api/users/me": "/users/me", + "https://example.com/api/users//alice": "/users/{id}", + "https://example.com/apistatus": "/{id}", + "https://example.com/api/status": "/status", + } { + request, _ := http.NewRequest(http.MethodGet, target, nil) + pathItem, errs, foundPath := FindPath(request, doc, opts) + assert.Empty(t, errs, "%s %s", name, target) + assert.NotNil(t, pathItem, "%s %s", name, target) + assert.Equal(t, expected, foundPath, "%s %s", name, target) + } + } +} + +func TestFindPath_DoubledSlashesThatMatchNothing(t *testing.T) { + doc, options := ambiguousPathOptions(t) + for name, opts := range options { + request, _ := http.NewRequest(http.MethodGet, "https://example.com/api/no//such/path/here", nil) + pathItem, errs, _ := FindPath(request, doc, opts) + assert.Nil(t, pathItem, name) + if assert.Len(t, errs, 1, name) { + assert.Equal(t, helpers.ValidationMissing, errs[0].ValidationSubType, name) + } + } +} + +func TestFindPath_AttachedRouteSkipsReadings(t *testing.T) { + doc, _ := ambiguousPathOptions(t) + request, _ := http.NewRequest(http.MethodGet, "https://example.com/api/users/m%65", nil) + + // the router that attached the route has already compared the readings + restore := requeststate.AttachRoute(request, &router.Route{Document: doc, RequestPath: "/users/m%65"}) + defer restore() + pathItem, errs, foundPath := FindPath(request, doc, nil) + assert.Empty(t, errs) + assert.NotNil(t, pathItem) + assert.Equal(t, "/users/{id}", foundPath) +} diff --git a/radix/tree.go b/radix/tree.go index 1a7c759..8201783 100644 --- a/radix/tree.go +++ b/radix/tree.go @@ -217,24 +217,16 @@ func (t *Tree[T]) walkRecursive(n *node[T], fn func(path string, value T) bool) return true } -// splitPath splits a path into segments, removing empty segments. -// "/users/{id}/posts" -> ["users", "{id}", "posts"] +// splitPath splits a path into segments, ignoring leading and trailing slashes. An empty segment +// between doubled slashes is kept and matched like any other, as the regex matcher does, so +// "/items//5" finds "/items/{a}/{b}" and not "/items/{id}". +// "/users/{id}/posts" -> ["users", "{id}", "posts"], "/a//b" -> ["a", "", "b"] func splitPath(path string) []string { path = strings.Trim(path, "/") if path == "" { return nil } - - parts := strings.Split(path, "/") - - // Filter out empty segments (from double slashes, etc.) - result := make([]string, 0, len(parts)) - for _, p := range parts { - if p != "" { - result = append(result, p) - } - } - return result + return strings.Split(path, "/") } // isParam checks if a segment is a parameter (e.g., "{id}") diff --git a/radix/tree_test.go b/radix/tree_test.go index 5f4959e..9f315ca 100644 --- a/radix/tree_test.go +++ b/radix/tree_test.go @@ -553,7 +553,7 @@ func TestSplitPath(t *testing.T) { {"", nil}, {"users", []string{"users"}}, {"/a/b/c", []string{"a", "b", "c"}}, - {"//a//b//", []string{"a", "b"}}, // double slashes filtered + {"//a//b//", []string{"a", "", "b"}}, // outer slashes trimmed, inner empty segment kept {"/a/", []string{"a"}}, {"///", nil}, // all slashes } @@ -867,3 +867,30 @@ func BenchmarkTree_Lookup_VaryingIDs(b *testing.B) { tree.Lookup(testPaths[i%1000]) } } + +func TestTree_EmptySegments(t *testing.T) { + tree := New[string]() + tree.Insert("/items/{id}", "item") + tree.Insert("/items/{a}/{b}", "pair") + tree.Insert("/files/{name}", "file") + tree.Insert("/docs//raw", "raw") + + // an empty segment matches a parameter, as the regex matcher does + val, path, found := tree.Lookup("/items//5") + assert.True(t, found) + assert.Equal(t, "pair", val) + assert.Equal(t, "/items/{a}/{b}", path) + + // an empty segment is not skipped + _, _, found = tree.Lookup("/files//report") + assert.False(t, found) + + // an empty literal segment matches exactly + val, path, found = tree.Lookup("/docs//raw") + assert.True(t, found) + assert.Equal(t, "raw", val) + assert.Equal(t, "/docs//raw", path) + + _, _, found = tree.Lookup("/docs/x/raw") + assert.False(t, found) +} diff --git a/router/router.go b/router/router.go index fd964e4..f949b0b 100644 --- a/router/router.go +++ b/router/router.go @@ -23,6 +23,7 @@ import ( v3 "github.com/pb33f/libopenapi/datamodel/high/v3" + "github.com/pb33f/libopenapi-validator/internal/pathvariant" "github.com/pb33f/libopenapi-validator/radix" ) @@ -32,6 +33,11 @@ var ( // ErrMethodNotAllowed identifies requests whose path exists but method does not. // FindRoute returns a partial Route alongside this error. ErrMethodNotAllowed = errors.New("openapi operation not found") + // ErrAmbiguousPath identifies requests whose path selects a different operation when its + // percent-encoding, encoded slashes, or empty and dot segments are normalized, so a router in + // front of or behind the validator could run an operation other than the one matched. + // It also matches ErrPathNotFound, so callers that only check for a missing path treat it as one. + ErrAmbiguousPath = fmt.Errorf("%w: ambiguous request path", ErrPathNotFound) ) // RegexCache stores compiled path expressions. config.RegexCache satisfies this contract. @@ -55,7 +61,9 @@ type Router interface { // // A method mismatch returns a non-nil partial Route and an error matching // ErrMethodNotAllowed. A server or path mismatch returns a nil Route and an - // error matching ErrPathNotFound. + // error matching ErrPathNotFound. A path whose normalized readings select + // different operations returns a nil Route and an error matching both + // ErrAmbiguousPath and ErrPathNotFound. FindRoute(*http.Request) (*Route, error) // Release drops document and router-owned lookup references. Injected lookups // and regex caches are borrowed and are never released by the router. @@ -83,7 +91,7 @@ type Route struct { // RouteError retains partial match context while supporting errors.Is. type RouteError struct { - Kind error // Kind is ErrPathNotFound or ErrMethodNotAllowed. + Kind error // Kind is ErrPathNotFound, ErrAmbiguousPath, or ErrMethodNotAllowed. Route *Route // Route is populated for method mismatches and nil for path misses. } @@ -176,17 +184,37 @@ func (r *routeFinder) FindRoute(request *http.Request) (*Route, error) { return nil, &RouteError{Kind: ErrPathNotFound} } + escapedPath := request.URL.EscapedPath() + route, err := r.findRoute(request, escapedPath) + if route == nil && strings.Contains(escapedPath, "//") { + // doubled slashes match as single ones when nothing matches them as sent + route, err = r.findRoute(request, pathvariant.CollapseSlashes(escapedPath)) + } + if err != nil { + return route, err + } + // a router that reads the path another way must run the same operation, or the request is rejected + for _, variant := range pathvariant.Variants(escapedPath) { + if other, otherErr := r.findRoute(request, variant); otherErr == nil && other.Operation != route.Operation { + return nil, &RouteError{Kind: ErrAmbiguousPath} + } + } + return route, nil +} + +// findRoute matches one reading of the escaped request path. +func (r *routeFinder) findRoute(request *http.Request, escapedPath string) (*Route, error) { if r.pathOnly { - return r.findPathOnly(request) + return r.findPathOnly(request, escapedPath) } if len(r.servers) == 0 { - return r.find(request, request.URL.EscapedPath(), nil, nil) + return r.find(request, escapedPath, nil, nil) } var partial *Route for _, server := range r.servers { - path, params, ok := matchCompiledServer(request, server, r.serverMatch[server]) + path, params, ok := matchCompiledServer(request, escapedPath, server, r.serverMatch[server]) if !ok { continue } @@ -202,7 +230,7 @@ func (r *routeFinder) FindRoute(request *http.Request) (*Route, error) { } partial = route } - implicit, implicitErr := r.find(request, request.URL.EscapedPath(), nil, nil) + implicit, implicitErr := r.find(request, escapedPath, nil, nil) if implicit != nil && usesImplicitServer(implicit.Operation, implicit.PathItem, r.document) { if implicitErr == nil { return implicit, nil @@ -219,10 +247,10 @@ func (r *routeFinder) FindRoute(request *http.Request) (*Route, error) { // findPathOnly matches the request path, without its server base path, against the document paths. // Each candidate path is tried in order; a method mismatch is returned only when no candidate matches. -func (r *routeFinder) findPathOnly(request *http.Request) (*Route, error) { +func (r *routeFinder) findPathOnly(request *http.Request, escapedPath string) (*Route, error) { var partial *Route var partialErr error - for _, candidate := range compatibilityCandidates(request, r.document) { + for _, candidate := range compatibilityCandidates(request, escapedPath, r.document) { route, err := r.find(request, candidate.path, candidate.server, nil) if err == nil { return route, nil diff --git a/router/router_test.go b/router/router_test.go index fa304ef..3093f6d 100644 --- a/router/router_test.go +++ b/router/router_test.go @@ -468,7 +468,7 @@ func TestServerHelperEdges(t *testing.T) { _, _, ok := matchServer(nil, &v3.Server{URL: "/"}) assert.False(t, ok) - _, _, ok = matchCompiledServer(httptestRequest(http.MethodGet, "http://example.com/x"), &v3.Server{URL: "/"}, nil) + _, _, ok = matchCompiledServer(httptestRequest(http.MethodGet, "http://example.com/x"), "/x", &v3.Server{URL: "/"}, nil) assert.False(t, ok) _, _, ok = matchServer(&http.Request{}, &v3.Server{URL: "/"}) assert.False(t, ok) @@ -498,15 +498,15 @@ func TestServerHelperEdges(t *testing.T) { func TestCompatibilityPathEdges(t *testing.T) { request := &http.Request{URL: &url.URL{Path: "plain", Fragment: "frag"}} - assert.Equal(t, []compatibilityCandidate{{path: "/plain#frag"}}, compatibilityCandidates(request, nil)) + assert.Equal(t, []compatibilityCandidate{{path: "/plain#frag"}}, compatibilityCandidates(request, request.URL.EscapedPath(), nil)) doc := &v3.Document{Servers: []*v3.Server{nil, {URL: "http://[::1"}, {URL: "/api"}, {URL: "/api/v2"}}} request.URL = &url.URL{Path: "/api/v2/items"} assert.Equal(t, []compatibilityCandidate{{"/v2/items", doc.Servers[2]}, {"/items", doc.Servers[3]}}, - compatibilityCandidates(request, doc)) + compatibilityCandidates(request, request.URL.EscapedPath(), doc)) request.URL = &url.URL{Path: "/other"} - assert.Equal(t, []compatibilityCandidate{{path: "/other"}}, compatibilityCandidates(request, doc)) + assert.Equal(t, []compatibilityCandidate{{path: "/other"}}, compatibilityCandidates(request, request.URL.EscapedPath(), doc)) } func TestRouterPathOnlyTriesEveryMatchingServer(t *testing.T) { @@ -572,6 +572,87 @@ paths: wg.Wait() } +const ambiguitySpec = `openapi: 3.1.0 +info: {title: ambiguity, version: 1.0.0} +servers: [{url: https://example.com/api}] +paths: + /users/me: + get: {responses: {"200": {description: ok}}} + /users/{id}: + get: {responses: {"200": {description: ok}}} + /users/{id}/secrets: + get: {responses: {"200": {description: ok}}} + /items/{id}: + get: {responses: {"200": {description: ok}}} + /items/{a}/{b}: + get: {responses: {"200": {description: ok}}} + /status: + get: {responses: {"200": {description: ok}}} + /{id}: + get: {responses: {"200": {description: ok}}} +` + +func TestRouterRejectsAmbiguousPaths(t *testing.T) { + doc := model(t, ambiguitySpec) + for name, r := range map[string]Router{ + "path-only": NewRouter(doc, WithPathOnlyMatching()), + "strict": NewRouter(doc), + } { + for _, target := range []string{ + "https://example.com/api/users/m%65", + "https://example.com/api/users/%6D%65", + "https://example.com/api/users/5%2Fsecrets", + "https://example.com/api/items//5", + "https://example.com/api/users/../secrets", + } { + route, err := r.FindRoute(httptestRequest(http.MethodGet, target)) + assert.Nil(t, route, "%s %s", name, target) + assert.ErrorIs(t, err, ErrAmbiguousPath, "%s %s", name, target) + assert.ErrorIs(t, err, ErrPathNotFound, "%s %s", name, target) + } + + // readings that agree, or that match nothing, keep the route as sent + for target, expected := range map[string]string{ + "https://example.com/api/users/a%20b": "/users/{id}", + "https://example.com/api/users/%61lice": "/users/{id}", + "https://example.com/api/status%2Fx": "/{id}", + "https://example.com/api/users//alice": "/users/{id}", + "https://example.com/api/users/me": "/users/me", + "https://example.com/api/users/5/secrets": "/users/{id}/secrets", + } { + route, err := r.FindRoute(httptestRequest(http.MethodGet, target)) + require.NoError(t, err, "%s %s", name, target) + assert.Equal(t, expected, route.Path, "%s %s", name, target) + } + + // doubled slashes that match nothing, even collapsed, are not found + route, err := r.FindRoute(httptestRequest(http.MethodGet, "https://example.com/api/no//such/path/here")) + assert.Nil(t, route, name) + assert.ErrorIs(t, err, ErrPathNotFound, name) + assert.NotErrorIs(t, err, ErrAmbiguousPath, name) + + // a method mismatch is reported as sent, before readings are compared + route, err = r.FindRoute(httptestRequest(http.MethodPost, "https://example.com/api/users/m%65")) + assert.ErrorIs(t, err, ErrMethodNotAllowed, name) + assert.Equal(t, "/users/{id}", route.Path, name) + } +} + +func TestRouterBasePathEndsOnSegmentBoundary(t *testing.T) { + r := NewRouter(model(t, ambiguitySpec), WithPathOnlyMatching()) + + route, err := r.FindRoute(httptestRequest(http.MethodGet, "/apistatus")) + require.NoError(t, err) + assert.Equal(t, "/{id}", route.Path) + assert.Equal(t, map[string]string{"id": "apistatus"}, route.PathParams) + assert.Nil(t, route.Server) + + route, err = r.FindRoute(httptestRequest(http.MethodGet, "/api/status")) + require.NoError(t, err) + assert.Equal(t, "/status", route.Path) + assert.NotNil(t, route.Server) +} + func httptestRequest(method, target string) *http.Request { parsed, err := url.Parse(target) if err != nil { diff --git a/router/server.go b/router/server.go index f5fa8b7..e5c5717 100644 --- a/router/server.go +++ b/router/server.go @@ -90,7 +90,7 @@ func matchServer(request *http.Request, server *v3.Server) (string, map[string]s if err != nil { return "", nil, false } - return matchCompiledServer(request, server, &compiledServer{expression: expression, names: names, absolute: absolute}) + return matchCompiledServer(request, request.URL.EscapedPath(), server, &compiledServer{expression: expression, names: names, absolute: absolute}) } func normalizeServerTemplate(server *v3.Server) (string, bool) { @@ -109,11 +109,12 @@ func normalizeServerTemplate(server *v3.Server) (string, bool) { return template, absolute } -func matchCompiledServer(request *http.Request, server *v3.Server, compiled *compiledServer) (string, map[string]string, bool) { +// matchCompiledServer matches escapedPath, one reading of the request path, against a server. +func matchCompiledServer(request *http.Request, escapedPath string, server *v3.Server, compiled *compiledServer) (string, map[string]string, bool) { if request == nil || request.URL == nil || server == nil || compiled == nil { return "", nil, false } - target := request.URL.EscapedPath() + target := escapedPath if compiled.absolute { scheme := request.URL.Scheme if scheme == "" { @@ -200,25 +201,28 @@ type compatibilityCandidate struct { server *v3.Server } -// compatibilityCandidates returns the paths path-only matching tries for a request: the request path -// with the base path of each document server that prefixes it removed, in document order, or the -// request path as sent when no server does. Trying every server lets a later, more specific server -// match when an earlier one leaves a path the document does not declare. -func compatibilityCandidates(request *http.Request, document *v3.Document) []compatibilityCandidate { - path := request.URL.EscapedPath() +// compatibilityCandidates returns the paths path-only matching tries for escapedPath, one reading of +// the request path: the path with the base path of each document server that prefixes it on a segment +// boundary removed, in document order, or the path as given when no server does. Trying every server +// lets a later, more specific server match when an earlier one leaves a path the document does not declare. +func compatibilityCandidates(request *http.Request, escapedPath string, document *v3.Document) []compatibilityCandidate { var candidates []compatibilityCandidate if document != nil { for _, server := range document.Servers { if server == nil { continue } - if base := serverurl.BasePath(server.URL); base != "" && strings.HasPrefix(path, base) { - candidates = append(candidates, compatibilityCandidate{compatibilityPath(request, strings.TrimPrefix(path, base)), server}) + base := serverurl.BasePath(server.URL) + if base == "" { + continue + } + if rest, ok := serverurl.TrimBasePath(escapedPath, base); ok { + candidates = append(candidates, compatibilityCandidate{compatibilityPath(request, rest), server}) } } } if len(candidates) == 0 { - candidates = append(candidates, compatibilityCandidate{compatibilityPath(request, path), nil}) + candidates = append(candidates, compatibilityCandidate{compatibilityPath(request, escapedPath), nil}) } return candidates } diff --git a/validator_path_ambiguity_test.go b/validator_path_ambiguity_test.go new file mode 100644 index 0000000..aae1da3 --- /dev/null +++ b/validator_path_ambiguity_test.go @@ -0,0 +1,127 @@ +// Copyright 2023-2026 Princess Beef Heavy Industries, LLC / Dave Shanley +// SPDX-License-Identifier: MIT + +package validator + +import ( + "context" + "errors" + "net/http" + "testing" + + "github.com/pb33f/libopenapi" + "github.com/pb33f/testify/assert" + "github.com/pb33f/testify/require" + + "github.com/pb33f/libopenapi-validator/config" + validationErrors "github.com/pb33f/libopenapi-validator/errors" + "github.com/pb33f/libopenapi-validator/helpers" + "github.com/pb33f/libopenapi-validator/parameters" +) + +// Operations that a single request reaches under different readings of its path. +const ambiguousRouteSpec = `openapi: 3.1.0 +info: {title: ambiguous routes, version: "1"} +servers: [{url: https://example.com/api}] +components: + securitySchemes: + key: {type: apiKey, in: header, name: X-API-Key} +paths: + /users/{id}: + get: + parameters: + - {name: id, in: path, required: true, schema: {type: string}} + responses: {"200": {description: ok}} + /users/me: + get: + security: [{key: []}] + responses: {"200": {description: ok}} + /users/{id}/secrets: + get: + security: [{key: []}] + parameters: + - {name: id, in: path, required: true, schema: {type: string}} + responses: {"200": {description: ok}} + /status: + get: + responses: {"200": {description: ok}} + /{id}: + get: + security: [{key: []}] + parameters: + - {name: id, in: path, required: true, schema: {type: string}} + responses: {"200": {description: ok}} +` + +func TestValidateHttpRequest_AmbiguousPathsAreRejected(t *testing.T) { + document, err := libopenapi.NewDocument([]byte(ambiguousRouteSpec)) + require.NoError(t, err) + model, modelErr := document.BuildV3Model() + require.NoError(t, modelErr) + + calls := 0 + authenticate := config.WithAuthenticationFunc(func(_ context.Context, input *config.AuthenticationInput) error { + calls++ + if input.Request.Header.Get("X-API-Key") != "secret" { + return errors.New("bad key") + } + return nil + }) + + high, buildErrs := NewValidator(document, authenticate) + require.Empty(t, buildErrs) + strict, buildErrs := NewValidator(document, authenticate, config.WithStrictServerMatching()) + require.Empty(t, buildErrs) + standalone := parameters.NewParameterValidator(&model.Model, authenticate) + + validators := map[string]func(*http.Request) (bool, []*validationErrors.ValidationError){ + "path-only": high.ValidateHttpRequest, + "strict": strict.ValidateHttpRequest, + "standalone": func(request *http.Request) (bool, []*validationErrors.ValidationError) { + return standalone.ValidateSecurity(request) + }, + } + + for name, validate := range validators { + for _, target := range []string{ + "https://example.com/api/users/m%65", + "https://example.com/api/users/5%2Fsecrets", + } { + request, _ := http.NewRequest(http.MethodGet, target, nil) + valid, errs := validate(request) + assert.False(t, valid, "%s %s", name, target) + if assert.NotEmpty(t, errs, "%s %s", name, target) { + assert.Equal(t, helpers.ValidationAmbiguousPath, errs[0].ValidationSubType, "%s %s", name, target) + } + } + + // the operations still behave as declared + calls = 0 + request, _ := http.NewRequest(http.MethodGet, "https://example.com/api/users/alice", nil) + valid, _ := validate(request) + assert.True(t, valid, name) + assert.Zero(t, calls, name) + + request, _ = http.NewRequest(http.MethodGet, "https://example.com/api/users/me", nil) + valid, _ = validate(request) + assert.False(t, valid, name) + assert.Equal(t, 1, calls, name) + + request, _ = http.NewRequest(http.MethodGet, "https://example.com/api/users/me", nil) + request.Header.Set("X-API-Key", "secret") + valid, _ = validate(request) + assert.True(t, valid, name) + } + + // a base path is only removed on a segment boundary, so "/apistatus" is not "/status" + for name, validate := range map[string]func(*http.Request) (bool, []*validationErrors.ValidationError){ + "path-only": validators["path-only"], + "standalone": validators["standalone"], + } { + calls = 0 + request, _ := http.NewRequest(http.MethodGet, "https://example.com/apistatus", nil) + valid, _ := validate(request) + assert.False(t, valid, name) + assert.Equal(t, 1, calls, name) + } +}