11// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
22// SPDX-License-Identifier: Apache-2.0
33
4- //! Validation and logical application of middleware request- header mutations.
4+ //! Validation and logical application of HTTP middleware header mutations.
55
66use openshell_core:: proto:: { ExistingHeaderAction , HeaderMutation , HttpHeader , header_mutation} ;
77
88pub const MAX_HEADER_MUTATIONS : usize = 64 ;
99pub const MAX_HEADER_MUTATION_BYTES : usize = 32 * 1024 ;
1010
11+ /// Selects the protected-header rules for the HTTP message being mutated.
12+ #[ derive( Debug , Clone , Copy , PartialEq , Eq ) ]
13+ pub enum HeaderAuthority {
14+ Request ,
15+ Response ,
16+ }
17+
1118#[ derive( Debug , Clone , PartialEq , Eq ) ]
1219pub enum HeaderMutationError {
1320 TooMany { count : usize } ,
1421 InvalidName { name : String } ,
1522 Protected { name : String } ,
1623 HopByHop { name : String } ,
17- WriteNamespace { name : String } ,
1824 UnsafeValue { name : String } ,
1925 TooLarge ,
2026 InvalidExistingAction ,
@@ -31,7 +37,6 @@ impl HeaderMutationError {
3137 Self :: InvalidName { .. } => "header_mutation_invalid_name" ,
3238 Self :: Protected { .. } => "header_mutation_protected_header" ,
3339 Self :: HopByHop { .. } => "header_mutation_hop_by_hop_header" ,
34- Self :: WriteNamespace { .. } => "header_mutation_write_namespace" ,
3540 Self :: UnsafeValue { .. } => "header_mutation_unsafe_value" ,
3641 Self :: TooLarge => "header_mutation_bytes_over_capacity" ,
3742 Self :: InvalidExistingAction => "header_mutation_invalid_existing_action" ,
@@ -67,10 +72,6 @@ impl std::fmt::Display for HeaderMutationError {
6772 "middleware cannot mutate hop-by-hop header '{name}'"
6873 )
6974 }
70- Self :: WriteNamespace { name } => write ! (
71- formatter,
72- "middleware can only write request headers prefixed with x-openshell-middleware- and cannot write '{name}'"
73- ) ,
7475 Self :: UnsafeValue { name } => {
7576 write ! (
7677 formatter,
@@ -105,6 +106,7 @@ impl std::error::Error for HeaderMutationError {}
105106/// state observed by the next middleware. Repeated values and wire order are
106107/// preserved; comparisons are case-insensitive.
107108pub fn apply (
109+ authority : HeaderAuthority ,
108110 existing_headers : & [ HttpHeader ] ,
109111 connection_nominated_headers : & [ String ] ,
110112 mutations : & [ HeaderMutation ] ,
@@ -121,16 +123,12 @@ pub fn apply(
121123 match mutation. operation . as_ref ( ) {
122124 Some ( header_mutation:: Operation :: Write ( write) ) => {
123125 let name = validate_name ( & write. name ) ?;
126+ validate_authority ( authority, MutationKind :: Write , & write. name , & name) ?;
124127 if is_connection_nominated ( connection_nominated_headers, & name) {
125128 return Err ( HeaderMutationError :: HopByHop {
126129 name : write. name . clone ( ) ,
127130 } ) ;
128131 }
129- if !name. starts_with ( "x-openshell-middleware-" ) {
130- return Err ( HeaderMutationError :: WriteNamespace {
131- name : write. name . clone ( ) ,
132- } ) ;
133- }
134132 if !is_safe_value ( & write. value ) {
135133 return Err ( HeaderMutationError :: UnsafeValue {
136134 name : write. name . clone ( ) ,
@@ -166,6 +164,7 @@ pub fn apply(
166164 }
167165 Some ( header_mutation:: Operation :: Remove ( remove) ) => {
168166 let name = validate_name ( & remove. name ) ?;
167+ validate_authority ( authority, MutationKind :: Remove , & remove. name , & name) ?;
169168 if is_connection_nominated ( connection_nominated_headers, & name) {
170169 return Err ( HeaderMutationError :: HopByHop {
171170 name : remove. name . clone ( ) ,
@@ -195,12 +194,34 @@ fn validate_name(name: &str) -> Result<String, HeaderMutationError> {
195194 name : name. to_string ( ) ,
196195 } ) ;
197196 }
198- if is_protected ( & lower) {
197+ Ok ( lower)
198+ }
199+
200+ #[ derive( Debug , Clone , Copy , PartialEq , Eq ) ]
201+ enum MutationKind {
202+ Write ,
203+ Remove ,
204+ }
205+
206+ fn validate_authority (
207+ authority : HeaderAuthority ,
208+ kind : MutationKind ,
209+ original_name : & str ,
210+ normalized_name : & str ,
211+ ) -> Result < ( ) , HeaderMutationError > {
212+ let protected = match authority {
213+ HeaderAuthority :: Request => is_request_protected ( normalized_name) ,
214+ HeaderAuthority :: Response => {
215+ is_response_protected ( normalized_name)
216+ || ( kind == MutationKind :: Write && is_response_remove_only ( normalized_name) )
217+ }
218+ } ;
219+ if protected {
199220 return Err ( HeaderMutationError :: Protected {
200- name : name . to_string ( ) ,
221+ name : original_name . to_string ( ) ,
201222 } ) ;
202223 }
203- Ok ( lower )
224+ Ok ( ( ) )
204225}
205226
206227fn is_name_token_byte ( byte : u8 ) -> bool {
@@ -233,7 +254,7 @@ fn is_safe_value(value: &str) -> bool {
233254 . all ( |byte| byte == b'\t' || ( 0x20 ..=0x7e ) . contains ( & byte) || byte >= 0x80 )
234255}
235256
236- fn is_protected ( name : & str ) -> bool {
257+ fn is_request_protected ( name : & str ) -> bool {
237258 matches ! (
238259 name,
239260 "authorization"
@@ -253,6 +274,38 @@ fn is_protected(name: &str) -> bool {
253274 || name. starts_with ( "x-openshell-credential" )
254275}
255276
277+ fn is_response_protected ( name : & str ) -> bool {
278+ matches ! (
279+ name,
280+ "connection"
281+ | "content-encoding"
282+ | "content-length"
283+ | "content-range"
284+ | "keep-alive"
285+ | "proxy-authenticate"
286+ | "proxy-authorization"
287+ | "proxy-connection"
288+ | "te"
289+ | "trailer"
290+ | "transfer-encoding"
291+ | "upgrade"
292+ )
293+ }
294+
295+ fn is_response_remove_only ( name : & str ) -> bool {
296+ matches ! (
297+ name,
298+ "accept-ranges"
299+ | "etag"
300+ | "content-md5"
301+ | "digest"
302+ | "content-digest"
303+ | "repr-digest"
304+ | "signature"
305+ | "signature-input"
306+ )
307+ }
308+
256309fn is_connection_nominated ( connection_nominated_headers : & [ String ] , name : & str ) -> bool {
257310 connection_nominated_headers
258311 . iter ( )
@@ -292,6 +345,7 @@ mod tests {
292345 #[ test]
293346 fn protected_header_write_is_rejected ( ) {
294347 let error = apply (
348+ HeaderAuthority :: Request ,
295349 & [ ] ,
296350 & [ ] ,
297351 & [ write (
@@ -311,6 +365,7 @@ mod tests {
311365 #[ test]
312366 fn unsafe_header_value_is_rejected ( ) {
313367 let error = apply (
368+ HeaderAuthority :: Request ,
314369 & [ ] ,
315370 & [ ] ,
316371 & [ write (
@@ -330,6 +385,7 @@ mod tests {
330385 header ( "accept" , "application/json" ) ,
331386 ] ;
332387 let appended = apply (
388+ HeaderAuthority :: Request ,
333389 & existing,
334390 & [ ] ,
335391 & [ write (
@@ -349,6 +405,7 @@ mod tests {
349405 ) ;
350406
351407 let overwritten = apply (
408+ HeaderAuthority :: Request ,
352409 & existing,
353410 & [ ] ,
354411 & [ write (
@@ -367,6 +424,7 @@ mod tests {
367424 ) ;
368425
369426 let skipped = apply (
427+ HeaderAuthority :: Request ,
370428 & existing,
371429 & [ ] ,
372430 & [ write (
@@ -386,13 +444,25 @@ mod tests {
386444 header ( "accept" , "application/json" ) ,
387445 header ( "x-trace" , "two" ) ,
388446 ] ;
389- let updated = apply ( & existing, & [ ] , & [ remove ( "X-Trace" ) ] ) . expect ( "remove visible header" ) ;
447+ let updated = apply (
448+ HeaderAuthority :: Request ,
449+ & existing,
450+ & [ ] ,
451+ & [ remove ( "X-Trace" ) ] ,
452+ )
453+ . expect ( "remove visible header" ) ;
390454 assert_eq ! ( updated, vec![ header( "accept" , "application/json" ) ] ) ;
391455 }
392456
393457 #[ test]
394458 fn protected_header_remove_is_rejected_even_when_not_visible ( ) {
395- let error = apply ( & [ ] , & [ ] , & [ remove ( "Authorization" ) ] ) . expect_err ( "protected removal" ) ;
459+ let error = apply (
460+ HeaderAuthority :: Request ,
461+ & [ ] ,
462+ & [ ] ,
463+ & [ remove ( "Authorization" ) ] ,
464+ )
465+ . expect_err ( "protected removal" ) ;
396466 assert ! (
397467 error
398468 . to_string( )
@@ -404,6 +474,7 @@ mod tests {
404474 fn connection_nominated_header_is_protected ( ) {
405475 let nominated = vec ! [ "x-openshell-middleware-tag" . to_string( ) ] ;
406476 let write_error = apply (
477+ HeaderAuthority :: Request ,
407478 & [ ] ,
408479 & nominated,
409480 & [ write (
@@ -419,12 +490,69 @@ mod tests {
419490 . contains( "hop-by-hop header 'X-OpenShell-Middleware-Tag'" )
420491 ) ;
421492
422- let remove_error = apply ( & [ ] , & nominated, & [ remove ( "X-OpenShell-Middleware-Tag" ) ] )
423- . expect_err ( "hop-by-hop removal" ) ;
493+ let remove_error = apply (
494+ HeaderAuthority :: Request ,
495+ & [ ] ,
496+ & nominated,
497+ & [ remove ( "X-OpenShell-Middleware-Tag" ) ] ,
498+ )
499+ . expect_err ( "hop-by-hop removal" ) ;
424500 assert ! (
425501 remove_error
426502 . to_string( )
427503 . contains( "hop-by-hop header 'X-OpenShell-Middleware-Tag'" )
428504 ) ;
429505 }
506+
507+ #[ test]
508+ fn request_write_accepts_end_to_end_header_without_namespace ( ) {
509+ let updated = apply (
510+ HeaderAuthority :: Request ,
511+ & [ ] ,
512+ & [ ] ,
513+ & [ write (
514+ "Cache-Control" ,
515+ "no-store" ,
516+ ExistingHeaderAction :: Overwrite ,
517+ ) ] ,
518+ )
519+ . expect ( "ordinary end-to-end request header" ) ;
520+
521+ assert_eq ! ( updated, vec![ header( "cache-control" , "no-store" ) ] ) ;
522+ }
523+
524+ #[ test]
525+ fn response_authority_allows_end_to_end_writes_and_integrity_removal ( ) {
526+ let existing = [ header ( "etag" , "old" ) , header ( "content-type" , "text/plain" ) ] ;
527+ let updated = apply (
528+ HeaderAuthority :: Response ,
529+ & existing,
530+ & [ ] ,
531+ & [
532+ write ( "Cache-Control" , "private" , ExistingHeaderAction :: Overwrite ) ,
533+ remove ( "ETag" ) ,
534+ ] ,
535+ )
536+ . expect ( "permitted response mutations" ) ;
537+
538+ assert_eq ! (
539+ updated,
540+ vec![
541+ header( "content-type" , "text/plain" ) ,
542+ header( "cache-control" , "private" ) ,
543+ ]
544+ ) ;
545+ }
546+
547+ #[ test]
548+ fn response_authority_rejects_framing_and_integrity_writes ( ) {
549+ for mutation in [
550+ remove ( "Content-Length" ) ,
551+ write ( "ETag" , "new" , ExistingHeaderAction :: Overwrite ) ,
552+ ] {
553+ let error = apply ( HeaderAuthority :: Response , & [ ] , & [ ] , & [ mutation] )
554+ . expect_err ( "protected response mutation" ) ;
555+ assert ! ( matches!( error, HeaderMutationError :: Protected { .. } ) ) ;
556+ }
557+ }
430558}
0 commit comments