address #191

Author: daveshanley

helpers/parameter_utilities.go

@@ -1,4 +1,4 @@
-// Copyright 2023 Princess B33f Heavy Industries / Dave Shanley
+// Copyright 2023-2026 Princess Beef Heavy Industries, LLC / Dave Shanley
 // SPDX-License-Identifier: MIT
 
 package helpers
@@ -158,6 +158,19 @@ func ExtractSecurityHeaderNames(
 	return headers
 }
 
+// EffectiveSecurityForOperation returns the security requirements that apply to the
+// operation matched by request method. It implements OpenAPI's inheritance rule:
+//   - If the operation defines security (even an empty array), use that.
+//   - Otherwise, fall back to the document-level global security.
+//   - Returns nil only when neither level defines security.
+func EffectiveSecurityForOperation(request *http.Request, item *v3.PathItem, docSecurity []*base.SecurityRequirement) []*base.SecurityRequirement {
+	op := ExtractOperation(request, item)
+	if op != nil && op.Security != nil {
+		return op.Security // operation-level (may be empty [] = "no security")
+	}
+	return docSecurity // nil when no global security either
+}
+
 func cast(v string) any {
 	if v == "true" || v == "false" {
 		b, _ := strconv.ParseBool(v)

helpers/parameter_utilities_test.go

@@ -1,4 +1,4 @@
-// Copyright 2023 Princess B33f Heavy Industries / Dave Shanley
+// Copyright 2023-2026 Princess Beef Heavy Industries, LLC / Dave Shanley
 // SPDX-License-Identifier: MIT
 
 package helpers
@@ -938,7 +938,7 @@ func TestConstructParamMapFromPipeEncodingWithSchema(t *testing.T) {
 	}
 	result := ConstructParamMapFromPipeEncodingWithSchema(params, sch)
 	props := result["key1"].(map[string]interface{})
-	require.Equal(t, "123", props["name"])    // string because schema says string
+	require.Equal(t, "123", props["name"])      // string because schema says string
 	require.Equal(t, int64(42), props["count"]) // int because schema says integer
 }
 
@@ -964,8 +964,8 @@ func TestConstructMapFromCSVWithSchema(t *testing.T) {
 		}),
 	}
 	result := ConstructMapFromCSVWithSchema("id,99,rank,3.5", sch)
-	require.Equal(t, "99", result["id"])       // string
-	require.Equal(t, 3.5, result["rank"])      // number
+	require.Equal(t, "99", result["id"])  // string
+	require.Equal(t, 3.5, result["rank"]) // number
 
 	// odd number of values
 	result = ConstructMapFromCSVWithSchema("id,99,rank", sch)
@@ -1042,3 +1042,65 @@ func TestConstructParamMapFromFormEncodingArrayWithSchema(t *testing.T) {
 	require.Equal(t, "val", props["key1"])
 	require.NotContains(t, props, "key2")
 }
+
+func TestEffectiveSecurityForOperation(t *testing.T) {
+	globalSecurity := []*base.SecurityRequirement{
+		{
+			Requirements: orderedmap.ToOrderedMap(map[string][]string{
+				"GlobalAuth": {},
+			}),
+		},
+	}
+
+	opSecurity := []*base.SecurityRequirement{
+		{
+			Requirements: orderedmap.ToOrderedMap(map[string][]string{
+				"OpAuth": {},
+			}),
+		},
+	}
+
+	t.Run("operation-level security wins over global", func(t *testing.T) {
+		pathItem := &v3.PathItem{
+			Get: &v3.Operation{Security: opSecurity},
+		}
+		request, _ := http.NewRequest(http.MethodGet, "/", nil)
+		result := EffectiveSecurityForOperation(request, pathItem, globalSecurity)
+		require.Equal(t, opSecurity, result)
+	})
+
+	t.Run("nil operation security falls back to global", func(t *testing.T) {
+		pathItem := &v3.PathItem{
+			Get: &v3.Operation{}, // Security is nil
+		}
+		request, _ := http.NewRequest(http.MethodGet, "/", nil)
+		result := EffectiveSecurityForOperation(request, pathItem, globalSecurity)
+		require.Equal(t, globalSecurity, result)
+	})
+
+	t.Run("empty operation security means no security (opt-out)", func(t *testing.T) {
+		pathItem := &v3.PathItem{
+			Get: &v3.Operation{Security: []*base.SecurityRequirement{}},
+		}
+		request, _ := http.NewRequest(http.MethodGet, "/", nil)
+		result := EffectiveSecurityForOperation(request, pathItem, globalSecurity)
+		require.NotNil(t, result)
+		require.Len(t, result, 0)
+	})
+
+	t.Run("both nil returns nil", func(t *testing.T) {
+		pathItem := &v3.PathItem{
+			Get: &v3.Operation{},
+		}
+		request, _ := http.NewRequest(http.MethodGet, "/", nil)
+		result := EffectiveSecurityForOperation(request, pathItem, nil)
+		require.Nil(t, result)
+	})
+
+	t.Run("nil operation falls back to global", func(t *testing.T) {
+		pathItem := &v3.PathItem{} // no Get operation
+		request, _ := http.NewRequest(http.MethodGet, "/", nil)
+		result := EffectiveSecurityForOperation(request, pathItem, globalSecurity)
+		require.Equal(t, globalSecurity, result)
+	})
+}

parameters/header_parameters.go

@@ -231,7 +231,7 @@ func (v *paramValidator) ValidateHeaderParamsWithPathItem(request *http.Request,
 		// Extract security headers applicable to this operation
 		var securityHeaders []string
 		if v.document.Components != nil && v.document.Components.SecuritySchemes != nil {
-			security := helpers.ExtractSecurityForOperation(request, pathItem)
+			security := helpers.EffectiveSecurityForOperation(request, pathItem, v.document.Security)
 			// Convert orderedmap to regular map for the helper
 			schemesMap := make(map[string]*v3.SecurityScheme)
 			for pair := v.document.Components.SecuritySchemes.First(); pair != nil; pair = pair.Next() {

parameters/header_parameters_test.go

@@ -1417,3 +1417,72 @@ paths:
 	assert.Len(t, errors, 1)
 	assert.Contains(t, errors[0].Message, "X-Custom")
 }
+
+func TestNewValidator_HeaderParams_StrictMode_GlobalSecurityScheme(t *testing.T) {
+	// Global security with HTTP basic auth — Authorization header should not trigger undeclared error in strict mode
+	spec := `openapi: 3.1.0
+info:
+  title: Test API
+  version: "1.0"
+paths:
+  /secure/resource:
+    get:
+      responses:
+        "200":
+          description: OK
+security:
+  - BasicAuth: []
+components:
+  securitySchemes:
+    BasicAuth:
+      type: http
+      scheme: basic`
+
+	doc, _ := libopenapi.NewDocument([]byte(spec))
+	m, _ := doc.BuildV3Model()
+	v := NewParameterValidator(&m.Model, config.WithStrictMode())
+
+	request, _ := http.NewRequest(http.MethodGet, "https://things.com/secure/resource", nil)
+	request.Header.Set("Authorization", "Basic dXNlcjpwYXNz")
+
+	valid, errors := v.ValidateHeaderParams(request)
+
+	// Authorization should be recognized as a valid header via global security
+	assert.True(t, valid)
+	assert.Len(t, errors, 0)
+}
+
+func TestNewValidator_HeaderParams_StrictMode_GlobalSecurityApiKey(t *testing.T) {
+	// Global security with apiKey in header — X-API-Key should not trigger undeclared error in strict mode
+	spec := `openapi: 3.1.0
+info:
+  title: Test API
+  version: "1.0"
+paths:
+  /secure/resource:
+    get:
+      responses:
+        "200":
+          description: OK
+security:
+  - ApiKeyAuth: []
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key`
+
+	doc, _ := libopenapi.NewDocument([]byte(spec))
+	m, _ := doc.BuildV3Model()
+	v := NewParameterValidator(&m.Model, config.WithStrictMode())
+
+	request, _ := http.NewRequest(http.MethodGet, "https://things.com/secure/resource", nil)
+	request.Header.Set("X-API-Key", "my-secret-key")
+
+	valid, errors := v.ValidateHeaderParams(request)
+
+	// X-API-Key should be recognized as a valid header via global security
+	assert.True(t, valid)
+	assert.Len(t, errors, 0)
+}

parameters/validate_security.go

@@ -1,4 +1,4 @@
-// Copyright 2023-2025 Princess Beef Heavy Industries, LLC / Dave Shanley
+// Copyright 2023-2026 Princess Beef Heavy Industries, LLC / Dave Shanley
 // SPDX-License-Identifier: MIT
 
 package parameters
@@ -42,10 +42,10 @@ func (v *paramValidator) ValidateSecurityWithPathItem(request *http.Request, pat
 	if !v.options.SecurityValidation {
 		return true, nil
 	}
-	// extract security for the operation
-	security := helpers.ExtractSecurityForOperation(request, pathItem)
+	// extract security for the operation, falling back to document-level global security
+	security := helpers.EffectiveSecurityForOperation(request, pathItem, v.document.Security)
 
-	if security == nil {
+	if len(security) == 0 {
 		return true, nil
 	}