fix: sanitize endpoint path params

Author: stainless-app[bot]

src/finch/_utils/__init__.py

@@ -1,3 +1,4 @@
+from ._path import path_template as path_template
 from ._sync import asyncify as asyncify
 from ._proxy import LazyProxy as LazyProxy
 from ._utils import (

src/finch/_utils/_path.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import re
+from typing import (
+    Any,
+    Mapping,
+    Callable,
+)
+from urllib.parse import quote
+
+# Matches '.' or '..' where each dot is either literal or percent-encoded (%2e / %2E).
+_DOT_SEGMENT_RE = re.compile(r"^(?:\.|%2[eE]){1,2}$")
+
+_PLACEHOLDER_RE = re.compile(r"\{(\w+)\}")
+
+
+def _quote_path_segment_part(value: str) -> str:
+    """Percent-encode `value` for use in a URI path segment.
+
+    Considers characters not in `pchar` set from RFC 3986 §3.3 to be unsafe.
+    https://datatracker.ietf.org/doc/html/rfc3986#section-3.3
+    """
+    # quote() already treats unreserved characters (letters, digits, and -._~)
+    # as safe, so we only need to add sub-delims, ':', and '@'.
+    # Notably, unlike the default `safe` for quote(), / is unsafe and must be quoted.
+    return quote(value, safe="!$&'()*+,;=:@")
+
+
+def _quote_query_part(value: str) -> str:
+    """Percent-encode `value` for use in a URI query string.
+
+    Considers &, = and characters not in `query` set from RFC 3986 §3.4 to be unsafe.
+    https://datatracker.ietf.org/doc/html/rfc3986#section-3.4
+    """
+    return quote(value, safe="!$'()*+,;:@/?")
+
+
+def _quote_fragment_part(value: str) -> str:
+    """Percent-encode `value` for use in a URI fragment.
+
+    Considers characters not in `fragment` set from RFC 3986 §3.5 to be unsafe.
+    https://datatracker.ietf.org/doc/html/rfc3986#section-3.5
+    """
+    return quote(value, safe="!$&'()*+,;=:@/?")
+
+
+def _interpolate(
+    template: str,
+    values: Mapping[str, Any],
+    quoter: Callable[[str], str],
+) -> str:
+    """Replace {name} placeholders in `template`, quoting each value with `quoter`.
+
+    Placeholder names are looked up in `values`.
+
+    Raises:
+        KeyError: If a placeholder is not found in `values`.
+    """
+    # re.split with a capturing group returns alternating
+    # [text, name, text, name, ..., text] elements.
+    parts = _PLACEHOLDER_RE.split(template)
+
+    for i in range(1, len(parts), 2):
+        name = parts[i]
+        if name not in values:
+            raise KeyError(f"a value for placeholder {{{name}}} was not provided")
+        val = values[name]
+        if val is None:
+            parts[i] = "null"
+        elif isinstance(val, bool):
+            parts[i] = "true" if val else "false"
+        else:
+            parts[i] = quoter(str(values[name]))
+
+    return "".join(parts)
+
+
+def path_template(template: str, /, **kwargs: Any) -> str:
+    """Interpolate {name} placeholders in `template` from keyword arguments.
+
+    Args:
+        template: The template string containing {name} placeholders.
+        **kwargs: Keyword arguments to interpolate into the template.
+
+    Returns:
+        The template with placeholders interpolated and percent-encoded.
+
+        Safe characters for percent-encoding are dependent on the URI component.
+        Placeholders in path and fragment portions are percent-encoded where the `segment`
+        and `fragment` sets from RFC 3986 respectively are considered safe.
+        Placeholders in the query portion are percent-encoded where the `query` set from
+        RFC 3986 §3.3 is considered safe except for = and & characters.
+
+    Raises:
+        KeyError: If a placeholder is not found in `kwargs`.
+        ValueError: If resulting path contains /./ or /../ segments (including percent-encoded dot-segments).
+    """
+    # Split the template into path, query, and fragment portions.
+    fragment_template: str | None = None
+    query_template: str | None = None
+
+    rest = template
+    if "#" in rest:
+        rest, fragment_template = rest.split("#", 1)
+    if "?" in rest:
+        rest, query_template = rest.split("?", 1)
+    path_template = rest
+
+    # Interpolate each portion with the appropriate quoting rules.
+    path_result = _interpolate(path_template, kwargs, _quote_path_segment_part)
+
+    # Reject dot-segments (. and ..) in the final assembled path.  The check
+    # runs after interpolation so that adjacent placeholders or a mix of static
+    # text and placeholders that together form a dot-segment are caught.
+    # Also reject percent-encoded dot-segments to protect against incorrectly
+    # implemented normalization in servers/proxies.
+    for segment in path_result.split("/"):
+        if _DOT_SEGMENT_RE.match(segment):
+            raise ValueError(f"Constructed path {path_result!r} contains dot-segment {segment!r} which is not allowed")
+
+    result = path_result
+    if query_template is not None:
+        result += "?" + _interpolate(query_template, kwargs, _quote_query_part)
+    if fragment_template is not None:
+        result += "#" + _interpolate(fragment_template, kwargs, _quote_fragment_part)
+
+    return result

src/finch/resources/hris/benefits/benefits.py

@@ -8,7 +8,7 @@
 
 from .... import _legacy_response
 from ...._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
-from ...._utils import maybe_transform, async_maybe_transform
+from ...._utils import path_template, maybe_transform, async_maybe_transform
 from ...._compat import cached_property
 from .individuals import (
     Individuals,
@@ -157,7 +157,7 @@ def retrieve(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return self._get(
-            f"/employer/benefits/{benefit_id}",
+            path_template("/employer/benefits/{benefit_id}", benefit_id=benefit_id),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -201,7 +201,7 @@ def update(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return self._post(
-            f"/employer/benefits/{benefit_id}",
+            path_template("/employer/benefits/{benefit_id}", benefit_id=benefit_id),
             body=maybe_transform({"description": description}, benefit_update_params.BenefitUpdateParams),
             options=make_request_options(
                 extra_headers=extra_headers,
@@ -414,7 +414,7 @@ async def retrieve(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return await self._get(
-            f"/employer/benefits/{benefit_id}",
+            path_template("/employer/benefits/{benefit_id}", benefit_id=benefit_id),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -460,7 +460,7 @@ async def update(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return await self._post(
-            f"/employer/benefits/{benefit_id}",
+            path_template("/employer/benefits/{benefit_id}", benefit_id=benefit_id),
             body=await async_maybe_transform({"description": description}, benefit_update_params.BenefitUpdateParams),
             options=make_request_options(
                 extra_headers=extra_headers,

src/finch/resources/hris/benefits/individuals.py

@@ -8,7 +8,7 @@
 
 from .... import _legacy_response
 from ...._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
-from ...._utils import maybe_transform, async_maybe_transform
+from ...._utils import path_template, maybe_transform, async_maybe_transform
 from ...._compat import cached_property
 from ...._resource import SyncAPIResource, AsyncAPIResource
 from ...._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper
@@ -84,7 +84,7 @@ def enroll_many(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return self._post(
-            f"/employer/benefits/{benefit_id}/individuals",
+            path_template("/employer/benefits/{benefit_id}/individuals", benefit_id=benefit_id),
             body=maybe_transform(individuals, Iterable[individual_enroll_many_params.Individual]),
             options=make_request_options(
                 extra_headers=extra_headers,
@@ -128,7 +128,7 @@ def enrolled_ids(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return self._get(
-            f"/employer/benefits/{benefit_id}/enrolled",
+            path_template("/employer/benefits/{benefit_id}/enrolled", benefit_id=benefit_id),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -175,7 +175,7 @@ def retrieve_many_benefits(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return self._get_api_list(
-            f"/employer/benefits/{benefit_id}/individuals",
+            path_template("/employer/benefits/{benefit_id}/individuals", benefit_id=benefit_id),
             page=SyncSinglePage[IndividualBenefit],
             options=make_request_options(
                 extra_headers=extra_headers,
@@ -226,7 +226,7 @@ def unenroll_many(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return self._delete(
-            f"/employer/benefits/{benefit_id}/individuals",
+            path_template("/employer/benefits/{benefit_id}/individuals", benefit_id=benefit_id),
             body=maybe_transform(
                 {"individual_ids": individual_ids}, individual_unenroll_many_params.IndividualUnenrollManyParams
             ),
@@ -300,7 +300,7 @@ async def enroll_many(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return await self._post(
-            f"/employer/benefits/{benefit_id}/individuals",
+            path_template("/employer/benefits/{benefit_id}/individuals", benefit_id=benefit_id),
             body=await async_maybe_transform(individuals, Iterable[individual_enroll_many_params.Individual]),
             options=make_request_options(
                 extra_headers=extra_headers,
@@ -344,7 +344,7 @@ async def enrolled_ids(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return await self._get(
-            f"/employer/benefits/{benefit_id}/enrolled",
+            path_template("/employer/benefits/{benefit_id}/enrolled", benefit_id=benefit_id),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -391,7 +391,7 @@ def retrieve_many_benefits(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return self._get_api_list(
-            f"/employer/benefits/{benefit_id}/individuals",
+            path_template("/employer/benefits/{benefit_id}/individuals", benefit_id=benefit_id),
             page=AsyncSinglePage[IndividualBenefit],
             options=make_request_options(
                 extra_headers=extra_headers,
@@ -442,7 +442,7 @@ async def unenroll_many(
         if not benefit_id:
             raise ValueError(f"Expected a non-empty value for `benefit_id` but received {benefit_id!r}")
         return await self._delete(
-            f"/employer/benefits/{benefit_id}/individuals",
+            path_template("/employer/benefits/{benefit_id}/individuals", benefit_id=benefit_id),
             body=await async_maybe_transform(
                 {"individual_ids": individual_ids}, individual_unenroll_many_params.IndividualUnenrollManyParams
             ),

src/finch/resources/hris/company/pay_statement_item/rules.py

@@ -9,7 +9,7 @@
 
 from ..... import _legacy_response
 from ....._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
-from ....._utils import maybe_transform, async_maybe_transform
+from ....._utils import path_template, maybe_transform, async_maybe_transform
 from ....._compat import cached_property
 from ....._resource import SyncAPIResource, AsyncAPIResource
 from ....._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper
@@ -143,7 +143,7 @@ def update(
         if not rule_id:
             raise ValueError(f"Expected a non-empty value for `rule_id` but received {rule_id!r}")
         return self._put(
-            f"/employer/pay-statement-item/rule/{rule_id}",
+            path_template("/employer/pay-statement-item/rule/{rule_id}", rule_id=rule_id),
             body=maybe_transform({"optional_property": optional_property}, rule_update_params.RuleUpdateParams),
             options=make_request_options(
                 extra_headers=extra_headers,
@@ -224,7 +224,7 @@ def delete(
         if not rule_id:
             raise ValueError(f"Expected a non-empty value for `rule_id` but received {rule_id!r}")
         return self._delete(
-            f"/employer/pay-statement-item/rule/{rule_id}",
+            path_template("/employer/pay-statement-item/rule/{rule_id}", rule_id=rule_id),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -351,7 +351,7 @@ async def update(
         if not rule_id:
             raise ValueError(f"Expected a non-empty value for `rule_id` but received {rule_id!r}")
         return await self._put(
-            f"/employer/pay-statement-item/rule/{rule_id}",
+            path_template("/employer/pay-statement-item/rule/{rule_id}", rule_id=rule_id),
             body=await async_maybe_transform(
                 {"optional_property": optional_property}, rule_update_params.RuleUpdateParams
             ),
@@ -434,7 +434,7 @@ async def delete(
         if not rule_id:
             raise ValueError(f"Expected a non-empty value for `rule_id` but received {rule_id!r}")
         return await self._delete(
-            f"/employer/pay-statement-item/rule/{rule_id}",
+            path_template("/employer/pay-statement-item/rule/{rule_id}", rule_id=rule_id),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,

src/finch/resources/hris/documents.py

@@ -9,7 +9,7 @@
 
 from ... import _legacy_response
 from ..._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
-from ..._utils import maybe_transform, async_maybe_transform
+from ..._utils import path_template, maybe_transform, async_maybe_transform
 from ..._compat import cached_property
 from ..._resource import SyncAPIResource, AsyncAPIResource
 from ..._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper
@@ -137,7 +137,7 @@ def retreive(
         return cast(
             DocumentRetreiveResponse,
             self._get(
-                f"/employer/documents/{document_id}",
+                path_template("/employer/documents/{document_id}", document_id=document_id),
                 options=make_request_options(
                     extra_headers=extra_headers,
                     extra_query=extra_query,
@@ -269,7 +269,7 @@ async def retreive(
         return cast(
             DocumentRetreiveResponse,
             await self._get(
-                f"/employer/documents/{document_id}",
+                path_template("/employer/documents/{document_id}", document_id=document_id),
                 options=make_request_options(
                     extra_headers=extra_headers,
                     extra_query=extra_query,

src/finch/resources/jobs/automated.py

@@ -8,7 +8,7 @@
 
 from ... import _legacy_response
 from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
-from ..._utils import required_args, maybe_transform, async_maybe_transform
+from ..._utils import path_template, required_args, maybe_transform, async_maybe_transform
 from ..._compat import cached_property
 from ..._resource import SyncAPIResource, AsyncAPIResource
 from ..._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper
@@ -182,7 +182,7 @@ def retrieve(
         if not job_id:
             raise ValueError(f"Expected a non-empty value for `job_id` but received {job_id!r}")
         return self._get(
-            f"/jobs/automated/{job_id}",
+            path_template("/jobs/automated/{job_id}", job_id=job_id),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -405,7 +405,7 @@ async def retrieve(
         if not job_id:
             raise ValueError(f"Expected a non-empty value for `job_id` but received {job_id!r}")
         return await self._get(
-            f"/jobs/automated/{job_id}",
+            path_template("/jobs/automated/{job_id}", job_id=job_id),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,

src/finch/resources/jobs/manual.py

@@ -6,6 +6,7 @@
 
 from ... import _legacy_response
 from ..._types import Body, Query, Headers, NotGiven, not_given
+from ..._utils import path_template
 from ..._compat import cached_property
 from ..._resource import SyncAPIResource, AsyncAPIResource
 from ..._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper
@@ -63,7 +64,7 @@ def retrieve(
         if not job_id:
             raise ValueError(f"Expected a non-empty value for `job_id` but received {job_id!r}")
         return self._get(
-            f"/jobs/manual/{job_id}",
+            path_template("/jobs/manual/{job_id}", job_id=job_id),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -123,7 +124,7 @@ async def retrieve(
         if not job_id:
             raise ValueError(f"Expected a non-empty value for `job_id` but received {job_id!r}")
         return await self._get(
-            f"/jobs/manual/{job_id}",
+            path_template("/jobs/manual/{job_id}", job_id=job_id),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,