feat(cors): support setting Access-Control-Allow-Private-Network in CORSMiddleware (#2475)

* feat(cors): support for private networks in `CORSMiddleware`

Adds support for sending `Access-Control-Allow-Private-Network` header in CORS preflight responses.
Its disabled by default, setting `allow_private_network` to True will enable support for private network
requests. Other two parameters are also optional, they can be considered as "metadata" (pna name & ID).

BREAKING CHANGE: nothing, all additional arguments have default value. Feature itself will not be injected unconditionally.

* chore: drop extra CORS options, adjust tests & news fragment accordingly

* perf: switch conditions related `allow_private_network` in `process_response` method

Author: AbduazizZiyodov

docs/_newsfragments/2381.newandimproved.rst

@@ -0,0 +1,4 @@
+Added support for private network requests in CORS middleware.
+This is off by default and can be enabled by passing the keyword argument 
+``allow_private_network=True`` to :class:`falcon.middleware.CORSMiddleware` 
+during initialization.

falcon/middleware.py

@@ -50,15 +50,25 @@ class CORSMiddleware(UniversalMiddlewareWithProcessResponse):
             The string ``'*'`` acts as a wildcard, matching every allowed origin,
             while ``None`` disallows all origins. This parameter takes effect only
             if the origin is allowed by the ``allow_origins`` argument.
-            (Default ``None``).
+            (default ``None``).
+        allow_private_network (bool):
+            If ``True``, the server includes the
+            ``Access-Control-Allow-Private-Network`` header in responses to
+            CORS preflight (OPTIONS) requests. This indicates that the resource is
+            willing to respond to requests from less-public IP address spaces
+            (e.g., from public site to private device).
+            (default ``False``).
 
+            See also:
+            https://wicg.github.io/private-network-access/#private-network-request-heading
     """
 
     def __init__(
         self,
         allow_origins: Union[str, Iterable[str]] = '*',
         expose_headers: Optional[Union[str, Iterable[str]]] = None,
         allow_credentials: Optional[Union[str, Iterable[str]]] = None,
+        allow_private_network: bool = False,
     ):
         if allow_origins == '*':
             self.allow_origins = allow_origins
@@ -88,6 +98,7 @@ def __init__(
                     'as a string literal, not inside an iterable.'
                 )
         self.allow_credentials = allow_credentials
+        self.allow_private_network = allow_private_network
 
     def process_response(
         self, req: Request, resp: Response, resource: object, req_succeeded: bool
@@ -146,6 +157,11 @@ def process_response(
                 resp.set_header('Access-Control-Allow-Headers', allow_headers)
                 resp.set_header('Access-Control-Max-Age', '86400')  # 24 hours
 
+            if self.allow_private_network and (
+                req.get_header('Access-Control-Request-Private-Network') == 'true'
+            ):
+                resp.set_header('Access-Control-Allow-Private-Network', 'true')
+
     async def process_response_async(
         self,
         req: AsgiRequest,

tests/test_cors_middleware.py

@@ -161,6 +161,32 @@ def my_sink(req, resp):
             assert 'Access-Control-Expose-Headers' not in result.headers
             assert 'Access-Control-Allow-Origin' not in result.headers
 
+    @pytest.mark.parametrize('include_request_private_network', (True, False))
+    def test_disabled_cors_private_network(
+        self, cors_client, include_request_private_network
+    ):
+        # default scenario for cors middleware, where
+        # allow private network is off by default
+
+        cors_client.app.add_route('/', CORSHeaderResource())
+
+        headers = (
+            ('Origin', 'localhost'),
+            ('Access-Control-Request-Method', 'GET'),
+        )
+
+        if include_request_private_network:
+            headers = (
+                *headers,
+                ('Access-Control-Request-Private-Network', 'true'),
+            )
+
+        result = cors_client.simulate_options('/', headers=headers)
+
+        h = result.headers
+
+        assert 'Access-Control-Allow-Private-Network' not in h
+
 
 @pytest.fixture(scope='function')
 def make_cors_client(asgi, util):
@@ -293,3 +319,19 @@ def test_expose_headers(self, make_cors_client, attr, exp):
         assert res.headers['Access-Control-Expose-Headers'] == exp
         h = dict(res.headers.lower_items()).keys()
         assert 'Access-Control-Allow-Credentials'.lower() not in h
+
+    def test_enabled_cors_private_network_headers(self, make_cors_client):
+        client = make_cors_client(falcon.CORSMiddleware(allow_private_network=True))
+
+        client.app.add_route('/', CORSHeaderResource())
+
+        res = client.simulate_options(
+            '/',
+            headers=(
+                ('Origin', 'localhost'),
+                ('Access-Control-Request-Method', 'GET'),
+                ('Access-Control-Request-Private-Network', 'true'),
+            ),
+        )
+
+        assert res.headers['Access-Control-Allow-Private-Network'] == 'true'