salesforce-data-customcode 6.1.0.dev5__tar.gz → 6.1.0.dev7__tar.gz

{salesforce_data_customcode-6.1.0.dev5 → salesforce_data_customcode-6.1.0.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: salesforce-data-customcode
-Version: 6.1.0.dev5
+Version: 6.1.0.dev7
 Summary: Data Cloud Custom Code SDK
 License-Expression: Apache-2.0
 License-File: LICENSE.txt

{salesforce_data_customcode-6.1.0.dev5 → salesforce_data_customcode-6.1.0.dev7}/pyproject.toml

@@ -18,7 +18,7 @@ license = "Apache-2.0"
 name = "salesforce-data-customcode"
 readme = "README.md"
 requires-python = ">=3.10,<3.12"
-version = "6.1.0.dev5"
+version = "6.1.0.dev7"
 
 [tool.black]
 exclude = '''

{salesforce_data_customcode-6.1.0.dev5 → salesforce_data_customcode-6.1.0.dev7}/src/datacustomcode/client.py

@@ -32,6 +32,7 @@ from datacustomcode.einstein_predictions_config import spark_einstein_prediction
 from datacustomcode.file.path.default import DefaultFindFilePath
 from datacustomcode.io.reader.base import BaseDataCloudReader
 from datacustomcode.llm_gateway_config import spark_llm_gateway_config
+from datacustomcode.named_credential_config import spark_named_credential_config
 from datacustomcode.spark.default import DefaultSparkSessionProvider
 
 if TYPE_CHECKING:
@@ -49,6 +50,9 @@ if TYPE_CHECKING:
     from datacustomcode.io.reader.base import BaseDataCloudReader
     from datacustomcode.io.writer.base import BaseDataCloudWriter, WriteMode
     from datacustomcode.llm_gateway.spark_base import SparkLLMGateway
+    from datacustomcode.named_credential.spark_base import SparkNamedCredential
+    from datacustomcode.named_credential.types.http_request import HTTPRequest
+    from datacustomcode.named_credential.types.http_response import HTTPResponse
     from datacustomcode.spark.base import BaseSparkSessionProvider
 
 
@@ -160,6 +164,21 @@ def _build_spark_einstein_predictions() -> "SparkEinsteinPredictions":
     return cfg.to_object()
 
 
+def _build_spark_named_credential() -> "SparkNamedCredential":
+    """Instantiate the SDK-configured :class:`SparkNamedCredential`.
+
+    Raises:
+        RuntimeError: If no ``spark_named_credential_config`` has been loaded.
+    """
+    cfg = spark_named_credential_config.spark_named_credential_config
+    if cfg is None:
+        raise RuntimeError(
+            "spark_named_credential_config is not configured. Add a "
+            "'spark_named_credential_config' section to config.yaml."
+        )
+    return cfg.to_object()
+
+
 def einstein_predict_col(
     model_api_name: str,
     prediction_type: "PredictionType",
@@ -209,6 +228,40 @@ def einstein_predict_col(
     )
 
 
+def named_credential_request_col(
+    request: "HTTPRequest",
+    body: Optional["Column"] = None,
+) -> "Column":
+    """Build a Spark Column that makes one Named Credential callout per row.
+
+    The endpoint, method, and headers are fixed for the call (taken from
+    ``request``); only ``body`` varies per row. Use this instead of
+    :meth:`Client.named_credential_request` when the callout runs across a
+    DataFrame so each row is dispatched independently rather than one-shot on
+    the driver.
+
+    The returned Column yields a struct ``{status, response, error_code,
+    error_message}`` for each row. ``response`` is itself a struct
+    ``{status_code, body, headers}``. Use ``[...]`` to pick a field, e.g.
+    ``named_credential_request_col(...)["response"]["status_code"]``. A transport
+    failure sets ``status`` to ``ERROR`` and populates ``error_message`` (a non-2xx
+    HTTP response is still ``SUCCESS`` with its code in ``response.status_code``),
+    so a single bad row does not abort the whole Spark job.
+
+    Args:
+        request: The callout template — its symbolic reference, method, and
+            headers are applied to every row.
+        body: Optional per-row ``Column`` holding the request body as a
+            string (or null for no body).
+
+    Returns:
+        A Spark ``Column`` of ``StructType`` with fields ``status``,
+        ``response``, ``error_code``, and ``error_message``.
+    """
+    named_credential = Client()._get_spark_named_credential()
+    return named_credential.request_col(request, body=body)
+
+
 class DataCloudObjectType(Enum):
     DLO = "dlo"
     DMO = "dmo"
@@ -266,6 +319,14 @@ class _BaseClient:
         spark_llm_gateway: Optional custom :class:`SparkLLMGateway`.
         spark_einstein_predictions: Optional custom
             :class:`SparkEinsteinPredictions`.
+        spark_named_credential: Optional custom :class:`SparkNamedCredential`.
+
+    Example:
+    >>> client = Client()
+    >>> file_path = client.find_file_path("data.csv")
+    >>> dlo = client.read_dlo("my_dlo")
+    >>> client.write_to_dmo("my_dmo", dlo)
+    >>> answer = client.llm_gateway_generate_text("Generate a greeting message")
     """
 
     # Each concrete subclass gets its own ``_instance`` slot: reads fall through
@@ -285,6 +346,7 @@ class _BaseClient:
     _file: DefaultFindFilePath
     _spark_llm_gateway: Optional[SparkLLMGateway]
     _spark_einstein_predictions: Optional[SparkEinsteinPredictions]
+    _spark_named_credential: Optional[SparkNamedCredential]
     _data_layer_history: dict[DataCloudObjectType, set[str]]
     _code_type: str
 
@@ -295,6 +357,7 @@ class _BaseClient:
         spark_provider: Optional[BaseSparkSessionProvider] = None,
         spark_llm_gateway: Optional[SparkLLMGateway] = None,
         spark_einstein_predictions: Optional[SparkEinsteinPredictions] = None,
+        spark_named_credential: Optional[SparkNamedCredential] = None,
         code_type: str = "script",
     ) -> _ClientT:
 
@@ -302,6 +365,7 @@ class _BaseClient:
             instance = super().__new__(cls)
             instance._spark_llm_gateway = spark_llm_gateway
             instance._spark_einstein_predictions = spark_einstein_predictions
+            instance._spark_named_credential = spark_named_credential
             # Initialize Readers and Writers from config
             # and/or provided reader and writer
             if reader is None or writer is None:
@@ -474,6 +538,41 @@ class _BaseClient:
             self._spark_einstein_predictions = _build_spark_einstein_predictions()
         return self._spark_einstein_predictions
 
+    def named_credential_request(
+        self,
+        request: "HTTPRequest",
+        body: Optional[str] = None,
+    ) -> "HTTPResponse":
+        """Issue a one-shot Named Credential external callout. This is the
+        scalar counterpart to :func:`named_credential_request_col`: it runs
+        **once** on the driver — not per row. Use the column helper method
+        instead when you want to fan a callout out across every row of a
+        DataFrame.
+
+        Example:
+
+            >>> from datacustomcode.named_credential.types.http_request_builder \\
+            ...     import HTTPRequestBuilder
+            >>> request = (
+            ...     HTTPRequestBuilder().set_url("callout:NC/search").build()
+            ... )
+            >>> response = Client().named_credential_request(request)
+
+        Args:
+            request: The callout request
+            body: Optional request body. Set the ``Content-Type`` header to
+                match the format; the SDK does not assume or inject one.
+
+        Returns:
+            The external service's response.
+        """
+        return self._get_spark_named_credential().request(request, body=body)
+
+    def _get_spark_named_credential(self) -> SparkNamedCredential:
+        if self._spark_named_credential is None:
+            self._spark_named_credential = _build_spark_named_credential()
+        return self._spark_named_credential
+
     def _validate_data_layer_history_does_not_contain(
         self, data_cloud_object_type: DataCloudObjectType
     ) -> None:

{salesforce_data_customcode-6.1.0.dev5 → salesforce_data_customcode-6.1.0.dev7}/src/datacustomcode/config.yaml

@@ -34,3 +34,9 @@ llm_gateway_config:
 
 spark_llm_gateway_config:
   type_config_name: DefaultSparkLLMGateway
+
+named_credential_config:
+  type_config_name: DefaultNamedCredential
+
+spark_named_credential_config:
+  type_config_name: DefaultSparkNamedCredential

{salesforce_data_customcode-6.1.0.dev5 → salesforce_data_customcode-6.1.0.dev7}/src/datacustomcode/deploy.py

@@ -38,6 +38,9 @@ import requests
 
 from datacustomcode.cmd import cmd_output
 from datacustomcode.constants import REQUEST_TYPE_TO_FEATURE
+from datacustomcode.named_credential.direct.credentials import (
+    EXTERNAL_CALLOUT_CREDENTIAL,
+)
 from datacustomcode.scan import find_base_directory, get_package_type
 
 DATA_CUSTOM_CODE_PATH = "services/data/v63.0/ssot/data-custom-code"
@@ -248,6 +251,8 @@ DEPENDENCIES_ARCHIVE_PATH = os.path.join(
 )
 PY_FILES_PATH = os.path.join("payload", "py-files")
 ZIP_FILE_NAME = "deployment.zip"
+# Local-only files that must never be packaged into the deployment zip.
+EXCLUDED_FILES = (".DS_Store", EXTERNAL_CALLOUT_CREDENTIAL)
 
 
 def prepare_dependency_archive(
@@ -628,9 +633,9 @@ def zip(
 
     with zipfile.ZipFile(ZIP_FILE_NAME, "w", zipfile.ZIP_DEFLATED) as zipf:
         for root, dirs, files in os.walk(directory):
-            # Skip .DS_Store files when adding to zip
+            # Skip .DS_Store and local credentials.
             for file in files:
-                if file != ".DS_Store":
+                if file not in EXCLUDED_FILES:
                     abs_path = os.path.join(root, file)
                     arcname = os.path.relpath(abs_path, directory)
                     zipf.write(abs_path, arcname)

{salesforce_data_customcode-6.1.0.dev5 → salesforce_data_customcode-6.1.0.dev7}/src/datacustomcode/function/runtime.py

@@ -23,6 +23,8 @@ from datacustomcode.file.path.default import DefaultFindFilePath
 from datacustomcode.function.base import BaseRuntime
 from datacustomcode.llm_gateway.base import LLMGateway
 from datacustomcode.llm_gateway_config import llm_gateway_config
+from datacustomcode.named_credential.base import NamedCredential
+from datacustomcode.named_credential_config import named_credential_config
 
 
 class Runtime(BaseRuntime):
@@ -69,6 +71,7 @@ class Runtime(BaseRuntime):
         self._llm_gateway: Optional[LLMGateway] = None
         self._file = DefaultFindFilePath()
         self._einstein_predictions: Optional[EinsteinPredictions] = None
+        self._named_credential: Optional[NamedCredential] = None
 
     @property
     def llm_gateway(self) -> LLMGateway:
@@ -98,3 +101,16 @@ class Runtime(BaseRuntime):
                 einstein_predictions_config.einstein_predictions_config.to_object()
             )
         return self._einstein_predictions
+
+    @property
+    def named_credential(self) -> NamedCredential:
+        if self._named_credential is None:
+            if named_credential_config.named_credential_config is None:
+                raise RuntimeError(
+                    "Named Credential is not configured. Add "
+                    "'named_credential_config' section to config.yaml"
+                )
+            self._named_credential = (
+                named_credential_config.named_credential_config.to_object()
+            )
+        return self._named_credential

salesforce_data_customcode-6.1.0.dev7/src/datacustomcode/named_credential/__init__.py

@@ -0,0 +1,28 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from datacustomcode.named_credential.base import NamedCredential
+from datacustomcode.named_credential.default import DefaultNamedCredential
+from datacustomcode.named_credential.errors import NamedCredentialCallError
+from datacustomcode.named_credential.spark_base import SparkNamedCredential
+from datacustomcode.named_credential.spark_default import DefaultSparkNamedCredential
+
+__all__ = [
+    "DefaultNamedCredential",
+    "DefaultSparkNamedCredential",
+    "NamedCredential",
+    "NamedCredentialCallError",
+    "SparkNamedCredential",
+]

salesforce_data_customcode-6.1.0.dev7/src/datacustomcode/named_credential/base.py

@@ -0,0 +1,54 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Optional
+
+from datacustomcode.mixin import UserExtendableNamedConfigMixin
+
+if TYPE_CHECKING:
+    from datacustomcode.named_credential.types.http_request import HTTPRequest
+    from datacustomcode.named_credential.types.http_response import HTTPResponse
+
+
+class NamedCredential(ABC, UserExtendableNamedConfigMixin):
+    CONFIG_NAME: str
+
+    def __init__(self, **kwargs):
+        pass
+
+    @abstractmethod
+    def request(
+        self,
+        request: HTTPRequest,
+        body: Optional[str] = None,
+    ) -> HTTPResponse:
+        """Make an external callout through a Named Credential.
+
+        The endpoint and its authentication are resolved server-side from the
+        Named Credential referenced by ``request.url``; the function never sees
+        the external credential.
+
+        Args:
+            request: The callout request
+            body: Optional request body. Set the
+                ``Content-Type`` header to match the format; the SDK
+                does not assume or inject one.
+
+        Returns:
+            The external service's response.
+        """
+        ...

salesforce_data_customcode-6.1.0.dev7/src/datacustomcode/named_credential/default.py

@@ -0,0 +1,93 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import (
+    Any,
+    Dict,
+    Optional,
+)
+
+from datacustomcode.named_credential.base import NamedCredential
+from datacustomcode.named_credential.types.http_request import HTTPRequest
+from datacustomcode.named_credential.types.http_response import HTTPResponse
+from datacustomcode.named_credential.types.http_response_builder import (
+    HTTPResponseBuilder,
+)
+
+
+class DefaultNamedCredential(NamedCredential):
+    """
+    Executes the callout directly via :class:`DirectCalloutTransport`, resolving
+    the URL from the Named Credential Connect API (falling back to
+    ``external_callout_config.json``) and injecting auth from the same file.
+    """
+
+    CONFIG_NAME = "DefaultNamedCredential"
+
+    def __init__(
+        self,
+        credentials_profile: str = "default",
+        sf_cli_org: Optional[str] = None,
+        credential_file: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._credentials_profile = credentials_profile
+        self._sf_cli_org = sf_cli_org
+        self._credential_file = credential_file
+        self._transport: Optional[Any] = None
+
+    def request(
+        self,
+        request: HTTPRequest,
+        body: Optional[str] = None,
+    ) -> HTTPResponse:
+        # Body and response are treated as opaque strings; the SDK makes no
+        # assumption about their format (JSON, XML, text, ...).
+        callout_request = {
+            "path": request.url,
+            "method": request.method,
+            "headers": dict(request.headers),
+            "body": body if body is not None else "",
+        }
+        callout_response = self._callout(callout_request)
+        return HTTPResponseBuilder.build(
+            {
+                "status_code": callout_response.get("status_code"),
+                "headers": callout_response.get("headers", {}),
+                "body": callout_response.get("body") or "",
+            }
+        )
+
+    def _callout(self, callout_request: Dict[str, Any]) -> Dict[str, Any]:
+        """Execute the callout via the transport.
+
+        Returns a dict with ``status_code``, ``headers``, and ``body``.
+        """
+        result: Dict[str, Any] = self._get_transport().callout(callout_request)
+        return result
+
+    def _get_transport(self) -> Any:
+        if self._transport is None:
+            from datacustomcode.named_credential.direct.transport import (
+                DirectCalloutTransport,
+            )
+
+            self._transport = DirectCalloutTransport(
+                credentials_profile=self._credentials_profile,
+                sf_cli_org=self._sf_cli_org,
+                credential_file=self._credential_file,
+            )
+        return self._transport

salesforce_data_customcode-6.1.0.dev7/src/datacustomcode/named_credential/direct/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Named Credential callout path.
+
+This resolves the endpoint via the NamedCredential Connect API
+and injects auth from a developer-provided ``external_callout_config.json``
+"""

salesforce_data_customcode-6.1.0.dev7/src/datacustomcode/named_credential/direct/auth.py

@@ -0,0 +1,191 @@
+# Copyright (c) 2025, Salesforce, Inc.
+# SPDX-License-Identifier: Apache-2
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Inject external credential auth into an outgoing request.
+"""
+
+from __future__ import annotations
+
+import base64
+import datetime
+import hashlib
+import hmac
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+)
+import urllib.parse
+
+from requests.auth import AuthBase
+
+from datacustomcode.named_credential.direct.credentials import AuthType
+
+if TYPE_CHECKING:
+    from requests.models import PreparedRequest
+
+_SIGV4_ALGORITHM = "AWS4-HMAC-SHA256"
+
+
+class DynamicAuthHandler(AuthBase):
+    def __init__(self, cred_config: Dict[str, Any]) -> None:
+        self.config = cred_config
+        self.auth_type = cred_config.get("auth_type")
+
+    def __call__(self, request: PreparedRequest) -> PreparedRequest:
+        if self.auth_type == AuthType.BASIC.value:
+            user = self.config.get("username", "")
+            pwd = self.config.get("password", "")
+            token = base64.b64encode(f"{user}:{pwd}".encode()).decode()
+            request.headers["Authorization"] = f"Basic {token}"
+
+        elif self.auth_type == AuthType.CUSTOM.value:
+            for name, value in self.config.get("custom_headers", {}).items():
+                request.headers[name] = value
+
+        elif self.auth_type in (AuthType.OAUTH.value, AuthType.JWT.value):
+            bearer = self.config.get("access_token") or self.config.get("token")
+            if not bearer:
+                raise ValueError(
+                    f"'{self.auth_type}' auth requires an 'access_token' or 'token'."
+                )
+            request.headers["Authorization"] = f"Bearer {bearer}"
+
+        elif self.auth_type == AuthType.AWS_SIG_V4.value:
+            self._sign_aws_sigv4(request)
+
+        else:
+            raise ValueError(f"Unsupported auth_type '{self.auth_type}'.")
+
+        return request
+
+    def _sign_aws_sigv4(self, request: PreparedRequest) -> None:
+        """Sign ``request`` with AWS Signature Version 4.
+
+        Requires ``aws_access_key_id``, ``aws_secret_access_key``, ``aws_region``,
+        and ``aws_service`` in the credential config; ``aws_session_token`` is
+        optional (for temporary credentials). The signed date, payload hash, and
+        (when present) session token are added as ``x-amz-*`` headers so the sent
+        request matches what was signed.
+        """
+        access_key = self.config.get("aws_access_key_id")
+        secret_key = self.config.get("aws_secret_access_key")
+        region = self.config.get("aws_region")
+        service = self.config.get("aws_service")
+        session_token = self.config.get("aws_session_token")
+        missing = [
+            name
+            for name, value in (
+                ("aws_access_key_id", access_key),
+                ("aws_secret_access_key", secret_key),
+                ("aws_region", region),
+                ("aws_service", service),
+            )
+            if not value
+        ]
+        if missing:
+            raise ValueError(f"'{self.auth_type}' auth requires {', '.join(missing)}.")
+        access_key = str(access_key)
+        secret_key = str(secret_key)
+        region = str(region)
+        service = str(service)
+
+        parsed = urllib.parse.urlsplit(str(request.url or ""))
+        host = parsed.netloc
+        canonical_uri = urllib.parse.quote(parsed.path or "/", safe="/-_.~")
+        canonical_query = _canonical_query_string(parsed.query)
+
+        body = request.body or b""
+        if isinstance(body, str):
+            body = body.encode("utf-8")
+        payload_hash = hashlib.sha256(body).hexdigest()
+
+        now = datetime.datetime.now(datetime.timezone.utc)
+        amz_date = now.strftime("%Y%m%dT%H%M%SZ")
+        datestamp = now.strftime("%Y%m%d")
+
+        request.headers["x-amz-date"] = amz_date
+        request.headers["x-amz-content-sha256"] = payload_hash
+        if session_token:
+            request.headers["x-amz-security-token"] = session_token
+
+        signed = {
+            "host": host,
+            "x-amz-content-sha256": payload_hash,
+            "x-amz-date": amz_date,
+        }
+        if session_token:
+            signed["x-amz-security-token"] = session_token
+        signed_headers = ";".join(sorted(signed))
+        canonical_headers = "".join(
+            f"{name}:{signed[name]}\n" for name in sorted(signed)
+        )
+
+        canonical_request = "\n".join(
+            [
+                request.method or "GET",
+                canonical_uri,
+                canonical_query,
+                canonical_headers,
+                signed_headers,
+                payload_hash,
+            ]
+        )
+        credential_scope = f"{datestamp}/{region}/{service}/aws4_request"
+        string_to_sign = "\n".join(
+            [
+                _SIGV4_ALGORITHM,
+                amz_date,
+                credential_scope,
+                hashlib.sha256(canonical_request.encode("utf-8")).hexdigest(),
+            ]
+        )
+        signing_key = _derive_signing_key(secret_key, datestamp, region, service)
+        signature = hmac.new(
+            signing_key, string_to_sign.encode("utf-8"), hashlib.sha256
+        ).hexdigest()
+
+        request.headers["Authorization"] = (
+            f"{_SIGV4_ALGORITHM} Credential={access_key}/{credential_scope}, "
+            f"SignedHeaders={signed_headers}, Signature={signature}"
+        )
+
+
+def _canonical_query_string(query: str) -> str:
+    """Build the AWS Sig V4 canonical query string from a raw query string."""
+    pairs = urllib.parse.parse_qsl(query, keep_blank_values=True)
+    encoded = [
+        (
+            urllib.parse.quote(key, safe="-_.~"),
+            urllib.parse.quote(value, safe="-_.~"),
+        )
+        for key, value in pairs
+    ]
+    encoded.sort()
+    return "&".join(f"{key}={value}" for key, value in encoded)
+
+
+def _derive_signing_key(
+    secret_key: str, datestamp: str, region: str, service: str
+) -> bytes:
+    """Derive the AWS Sig V4 signing key via the chained HMAC-SHA256 sequence."""
+
+    def _hmac(key: bytes, msg: str) -> bytes:
+        return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
+
+    k_date = _hmac(f"AWS4{secret_key}".encode(), datestamp)
+    k_region = _hmac(k_date, region)
+    k_service = _hmac(k_region, service)
+    return _hmac(k_service, "aws4_request")