From d69a7f385d5fadca0e4dae5535b2987fea8ddf4e Mon Sep 17 00:00:00 2001 From: Dave Shanley Date: Tue, 10 Nov 2026 19:35:00 -0500 Subject: [PATCH] fix: match request paths the same way under every reading Routers read request paths differently: some decode each segment, some route on the fully decoded path, some on the escaped path, and some remove empty and dot segments. The validator read a path one way, so /users/m%65 matched /users/{id} while a router that decodes segments dispatched it to /users/me. The router now resolves the path as sent and under each normalized reading: decoded path characters, decoded slashes, and empty and dot segments removed. When two readings select different operations, the request fails with ValidationSubType "ambiguousPath" (router.ErrAmbiguousPath, which also matches router.ErrPathNotFound). paths.FindPath does the same when no router is configured. Server base paths are removed only on a segment boundary, so a base of /api no longer turns /apistatus into /status. The radix tree keeps empty segments, so /items//5 matches /items/{a}/{b} as the regex matcher does. When the path as sent matches nothing, doubled slashes are collapsed and matched again, as before. Co-Authored-By: Claude Opus 5.5 --- errors/parameters_howtofix.go | 1 + helpers/constants.go | 1 + internal/pathvariant/pathvariant.go | 133 +++++++++++++++++++++++ internal/pathvariant/pathvariant_test.go | 81 ++++++++++++++ internal/serverurl/serverurl.go | 10 ++ internal/serverurl/serverurl_test.go | 21 ++++ paths/paths.go | 72 ++++++++++-- paths/paths_test.go | 105 ++++++++++++++++++ radix/tree.go | 18 +-- radix/tree_test.go | 29 ++++- router/router.go | 44 ++++++-- router/router_test.go | 89 ++++++++++++++- router/server.go | 28 +++-- validator_path_ambiguity_test.go | 127 ++++++++++++++++++++++ 14 files changed, 713 insertions(+), 46 deletions(-) create mode 100644 internal/pathvariant/pathvariant.go create mode 100644 internal/pathvariant/pathvariant_test.go create mode 100644 validator_path_ambiguity_test.go diff --git a/errors/parameters_howtofix.go b/errors/parameters_howtofix.go index 143197ed..785b8aa8 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 f1e1f3b6..34774593 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 00000000..f3ba6b62 --- /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 00000000..0282ca86 --- /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 6d9a20b1..ab87966b 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 485de59b..d21d716c 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 ad9d8a17..7082ee7c 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 2bd6debd..9abbd221 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 1a7c7598..82017835 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 5f4959eb..9f315ca2 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 fd964e45..f949b0bb 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 fa304efd..3093f6d7 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 f5fa8b7c..e5c5717d 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 00000000..aae1da32 --- /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) + } +}