stx-python 0.6.0__py3-none-any.whl

stx/_settings.py

@@ -0,0 +1,203 @@
+"""Layered configuration for the STX client.
+
+Precedence, highest first:
+
+1. Constructor kwargs passed to ``STX(...)``.
+2. Environment variables: ``STX_HOST`` (or ``STX_BASE_URL``),
+   ``STX_REGION``, ``STX_ENV``, ``STX_KEY_ID``, ``STX_PRIVATE_KEY``,
+   ``STX_VERIFY_TLS``, ``STX_PROFILE``.
+3. Named profile in ``~/.stx/credentials`` (an INI file; ``STX_CREDENTIALS``
+   points elsewhere). The profile to use comes from the ``profile=`` kwarg,
+   then ``STX_PROFILE``, then ``default``. Profile keys: ``region``,
+   ``env``, ``host``, ``key_id``, ``private_key`` (PEM text or a path),
+   ``verify_tls``. The file is shared with the STX API examples, so
+   ``key_file`` is accepted as an alias of ``private_key`` and ``base_url``
+   as an alias of ``host``.
+4. Baked-in defaults (``verify_tls=True``, ``profile="default"``).
+
+This module resolves everything into a single :class:`ResolvedConfig`
+that the clients consume.
+"""
+
+from __future__ import annotations
+
+import configparser
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Union
+
+from stx.enums import Environment, Region
+from stx.exceptions import STXConfigException
+
+_DEFAULT_PROFILE_NAME = "default"
+
+
+def _default_profile_file(env_map) -> Path:
+    override = env_map.get("STX_CREDENTIALS")
+    if override:
+        return Path(os.path.expanduser(override))
+    return Path.home() / ".stx" / "credentials"
+
+
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+_FALSY = frozenset({"0", "false", "no", "off"})
+
+
+def _parse_bool(value: Optional[str], key: str) -> Optional[bool]:
+    """Parse a string boolean.
+
+    Returns None if ``value`` is None *or* an empty/whitespace string -
+    treating unset and blank the same way. ``STX_VERIFY_TLS=`` (set but
+    empty, which some shell tooling produces) falls through to the
+    profile/default layer instead of silently disabling TLS verification.
+    """
+    if value is None:
+        return None
+    lower = value.strip().lower()
+    if not lower:
+        return None
+    if lower in _TRUTHY:
+        return True
+    if lower in _FALSY:
+        return False
+    raise STXConfigException(
+        f"Invalid boolean for {key}: {value!r}. Use one of {sorted(_TRUTHY | _FALSY)}."
+    )
+
+
+@dataclass
+class ResolvedConfig:
+    """The final, fully-resolved configuration the STX client uses.
+
+    Exactly one of ``host`` or (``region``, ``env``) will be set.
+    """
+
+    host: Optional[str]
+    region: Optional[Union[Region, str]]
+    env: Optional[Union[Environment, str]]
+    verify_tls: bool
+    profile_name: str
+    profile_used: bool
+    key_id: Optional[str] = None
+    private_key: Optional[str] = None
+
+
+def _read_profile(
+    profile_name: str,
+    profile_file: Optional[Path] = None,
+) -> tuple[dict, bool]:
+    """Load ``[profile_name]`` from the credentials file.
+
+    Returns (values, was_file_present). Raises ``STXConfigException`` if the
+    file exists but the requested profile doesn't - callers asked for
+    something that isn't there.
+    """
+    path = profile_file or _default_profile_file(os.environ)
+    if not path.is_file():
+        return ({}, False)
+    parser = configparser.ConfigParser()
+    try:
+        parser.read(path, encoding="utf-8")
+    except configparser.Error as exc:
+        raise STXConfigException(f"Failed to parse credentials file {path}: {exc}") from exc
+    if not parser.has_section(profile_name):
+        if profile_name == _DEFAULT_PROFILE_NAME:
+            return ({}, True)
+        raise STXConfigException(
+            f"Profile {profile_name!r} not found in {path}. Available profiles: {parser.sections()}"
+        )
+    return ({k: v for k, v in parser.items(profile_name)}, True)
+
+
+_SENTINEL = object()
+
+
+def resolve_settings(
+    *,
+    region=_SENTINEL,
+    env=_SENTINEL,
+    host=_SENTINEL,
+    key_id=_SENTINEL,
+    private_key=_SENTINEL,
+    verify_tls=_SENTINEL,
+    profile=_SENTINEL,
+    profile_file: Optional[Path] = None,
+    environ: Optional[dict] = None,
+) -> ResolvedConfig:
+    """Merge constructor kwargs, env vars, and the active profile.
+
+    ``_SENTINEL`` means "the caller did not pass this kwarg." Use sentinels
+    instead of ``None`` because ``None`` is a legitimate explicit value for
+    some knobs (e.g. ``host=None`` to ignore a host in the profile).
+
+    The ``environ`` and ``profile_file`` params are injection points for
+    tests; production callers leave them unset.
+    """
+    env_map = environ if environ is not None else os.environ
+
+    # --- Step 1: which profile? ---
+    if profile is _SENTINEL:
+        profile_name = env_map.get("STX_PROFILE", _DEFAULT_PROFILE_NAME)
+    else:
+        profile_name = profile or _DEFAULT_PROFILE_NAME
+
+    profile_values, profile_file_existed = _read_profile(
+        profile_name, profile_file or _default_profile_file(env_map)
+    )
+    # Only treat the profile as "in use" if the user asked for a non-default
+    # section, or a default section was actually present.
+    profile_used = (
+        (profile is not _SENTINEL and profile is not None)
+        or "STX_PROFILE" in env_map
+        or (profile_file_existed and bool(profile_values))
+    )
+
+    def _pick(kwarg, env_keys, *profile_keys: str):
+        """Apply the precedence chain for a single knob.
+
+        Several ``profile_keys`` may be given; the first one present in
+        the profile wins. Used for the aliases the shared credentials
+        file allows (``key_file`` for ``private_key``, ``base_url`` for
+        ``host``).
+        """
+        if kwarg is not _SENTINEL:
+            return kwarg
+        for env_key in env_keys if isinstance(env_keys, tuple) else (env_keys,):
+            if env_map.get(env_key):
+                return env_map[env_key]
+        for key in profile_keys:
+            if key in profile_values:
+                return profile_values[key]
+        return None
+
+    host_v = _pick(host, ("STX_HOST", "STX_BASE_URL"), "host", "base_url")
+    region_v = _pick(region, "STX_REGION", "region")
+    env_v = _pick(env, "STX_ENV", "env")
+    key_id_v = _pick(key_id, "STX_KEY_ID", "key_id")
+    private_key_v = _pick(private_key, "STX_PRIVATE_KEY", "private_key", "key_file")
+
+    # verify_tls: bool with explicit-False support. The kwarg sentinel lets us
+    # distinguish "not passed" from "passed as False".
+    if verify_tls is not _SENTINEL:
+        verify_tls_v: bool = bool(verify_tls)
+    else:
+        env_bool = _parse_bool(env_map.get("STX_VERIFY_TLS"), "STX_VERIFY_TLS")
+        if env_bool is not None:
+            verify_tls_v = env_bool
+        elif "verify_tls" in profile_values:
+            parsed = _parse_bool(profile_values["verify_tls"], "verify_tls")
+            verify_tls_v = parsed if parsed is not None else True
+        else:
+            verify_tls_v = True
+
+    return ResolvedConfig(
+        host=host_v,
+        region=region_v,
+        env=env_v,
+        verify_tls=verify_tls_v,
+        profile_name=profile_name,
+        profile_used=profile_used,
+        key_id=key_id_v,
+        private_key=private_key_v,
+    )

stx/_signing.py

@@ -0,0 +1,229 @@
+"""API-key request signing (Ed25519).
+
+An STX API key is a key id plus an Ed25519 private key. Every request
+carries three headers built from a fresh timestamp:
+
+    X-STX-ACCESS-KEY         the key id
+    X-STX-ACCESS-TIMESTAMP   Unix time in milliseconds, as a decimal string
+    X-STX-ACCESS-SIGNATURE   base64 (standard alphabet, padded) Ed25519
+                             signature over the UTF-8 bytes of the message
+
+The signed message is a bare concatenation with no separator:
+
+    timestamp_ms + HTTP_METHOD_UPPERCASE + request_path
+
+The request body is deliberately not signed. The path includes its
+query string when there is one, never the scheme or host. The WebSocket
+handshake is the exception: it signs ``GET`` and the socket path with
+the query string dropped.
+
+This module holds no transport code. It builds messages, signs them and
+formats headers; the sync, async and WebSocket clients attach the
+headers in whatever way their transport supports.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import time
+from pathlib import Path
+from typing import Callable, Dict, Optional, Union
+from urllib.parse import urlparse
+
+from stx.exceptions import STXConfigException
+
+KEY_HEADER = "X-STX-ACCESS-KEY"
+TIMESTAMP_HEADER = "X-STX-ACCESS-TIMESTAMP"
+SIGNATURE_HEADER = "X-STX-ACCESS-SIGNATURE"
+
+WEBSOCKET_PATH = "/socket/websocket"
+
+Signer = Callable[[bytes], bytes]
+
+_PEM_MARKER = "-----BEGIN"
+
+
+def build_message(timestamp_ms: int, method: str, path: str) -> str:
+    """The string that gets signed: ``timestamp + METHOD + path``.
+
+    ``method`` is upper-cased because the server signs the upper form.
+    ``path`` is used verbatim; the caller decides whether the query
+    string belongs in it (HTTP: yes, WebSocket handshake: no).
+    """
+    if not method:
+        raise ValueError("HTTP method is required.")
+    if not path:
+        raise ValueError("Request path is required.")
+    return f"{timestamp_ms}{method.upper()}{path}"
+
+
+def request_path(url: str) -> str:
+    """Path plus query string of ``url``, as the HTTP signature wants it."""
+    parsed = urlparse(url)
+    path = parsed.path or "/"
+    if parsed.query:
+        return f"{path}?{parsed.query}"
+    return path
+
+
+def handshake_path(url: str) -> str:
+    """Path of ``url`` with the query string dropped, as the WebSocket
+    handshake signature wants it."""
+    return urlparse(url).path or "/"
+
+
+def _looks_like_pem(value: str) -> bool:
+    return _PEM_MARKER in value
+
+
+def load_private_key(value: Union[str, bytes, os.PathLike[str]]):
+    """Parse a PKCS#8 Ed25519 private key.
+
+    Accepts the PEM text itself, the PEM as bytes, or a path to a PEM
+    file (``~`` is expanded). Returns a
+    ``cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey``.
+    """
+    try:
+        from cryptography.hazmat.primitives import serialization
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+            Ed25519PrivateKey,
+        )
+    except ImportError as exc:  # pragma: no cover - dependency is declared
+        raise STXConfigException(
+            "API-key authentication needs the `cryptography` package. "
+            "Run `pip install cryptography` (it is a declared dependency of "
+            "stx-python, so a fresh install already has it)."
+        ) from exc
+
+    if isinstance(value, bytes):
+        pem_bytes = value
+    else:
+        text = os.fspath(value) if not isinstance(value, str) else value
+        if _looks_like_pem(text):
+            pem_bytes = text.encode("utf-8")
+        else:
+            path = Path(os.path.expanduser(text))
+            if not path.is_file():
+                raise STXConfigException(
+                    f"Private key not found at {path}. Pass either the path to "
+                    "a PEM file or the PEM text itself."
+                )
+            pem_bytes = path.read_bytes()
+
+    try:
+        key = serialization.load_pem_private_key(pem_bytes, password=None)
+    except (ValueError, TypeError) as exc:
+        raise STXConfigException(
+            "Private key is not valid PEM. Expected a PKCS#8 block beginning "
+            "'-----BEGIN PRIVATE KEY-----'."  # pragma: allowlist secret
+        ) from exc
+    if not isinstance(key, Ed25519PrivateKey):
+        raise STXConfigException("Private key is not an Ed25519 key. STX API keys use Ed25519.")
+    return key
+
+
+def signer_from_private_key(value: Union[str, bytes, os.PathLike[str]]) -> Signer:
+    """Parse the key once and return a ``bytes -> bytes`` signer.
+
+    Pure Ed25519 over the message bytes. Not Ed25519ph, which produces
+    a well-formed signature that never verifies server-side.
+    """
+    key = load_private_key(value)
+    return key.sign
+
+
+class ApiKeyCredentials:
+    """An STX API key: the key id sent with every request, and the means
+    of signing.
+
+    Build one from a PEM string or path::
+
+        ApiKeyCredentials("my-key-id", "~/.stx/us-demo.pem")
+
+    or from a caller-supplied signer, for keys held in an HSM or KMS::
+
+        ApiKeyCredentials("my-key-id", signer=lambda msg: kms.sign(msg))
+
+    The signer receives the message bytes and must return the raw
+    64-byte Ed25519 signature. The private key never leaves the process;
+    only signatures are transmitted.
+    """
+
+    __slots__ = ("_sign", "key_id")
+
+    def __init__(
+        self,
+        key_id: str,
+        private_key: Union[str, bytes, os.PathLike[str], None] = None,
+        *,
+        signer: Optional[Signer] = None,
+    ) -> None:
+        if not key_id or not str(key_id).strip():
+            raise STXConfigException("API key id is required.")
+        if signer is None and private_key is None:
+            raise STXConfigException(
+                "Either `private_key` (PEM text or path) or `signer` is required."
+            )
+        if signer is not None and private_key is not None:
+            raise STXConfigException("Pass `private_key` or `signer`, not both.")
+        self.key_id = str(key_id).strip()
+        self._sign: Signer = signer if signer is not None else signer_from_private_key(private_key)
+
+    def sign(self, message: bytes) -> bytes:
+        """Raw Ed25519 signature over ``message``."""
+        return self._sign(message)
+
+    def headers(
+        self,
+        method: str,
+        path: str,
+        timestamp_ms: Optional[int] = None,
+    ) -> Dict[str, str]:
+        """The three signed headers for one request.
+
+        A fresh timestamp is generated per call unless ``timestamp_ms``
+        is given (tests). Signatures must never be cached or reused: the
+        server rejects anything more than 30 seconds from its clock.
+        """
+        ts = int(time.time() * 1000) if timestamp_ms is None else int(timestamp_ms)
+        message = build_message(ts, method, path).encode("utf-8")
+        signature = base64.b64encode(self.sign(message)).decode("ascii")
+        return {
+            KEY_HEADER: self.key_id,
+            TIMESTAMP_HEADER: str(ts),
+            SIGNATURE_HEADER: signature,
+        }
+
+    def __repr__(self) -> str:
+        return f"ApiKeyCredentials(key_id={self.key_id!r})"
+
+
+def credentials_from_settings(
+    key_id: Optional[str],
+    private_key: Union[str, bytes, os.PathLike[str], None],
+    signer: Optional[Signer] = None,
+) -> Optional[ApiKeyCredentials]:
+    """Turn the resolved settings into credentials, or ``None`` when no
+    API key is configured at all.
+
+    ``None`` is allowed so a client can be built for the public market
+    channels, which accept an unsigned socket. A REST call without a key
+    raises ``STXConfigException``. A key id without key material, or key
+    material without a key id, raises here.
+    """
+    has_material = private_key is not None or signer is not None
+    if not key_id and not has_material:
+        return None
+    if key_id and not has_material:
+        raise STXConfigException(
+            "key_id is set but no private key was given. Pass `private_key=` "
+            "(PEM text or path), set STX_PRIVATE_KEY, or add `private_key` to "
+            "the profile in ~/.stx/credentials."
+        )
+    if has_material and not key_id:
+        raise STXConfigException(
+            "A private key was given but no key_id. Pass `key_id=`, set "
+            "STX_KEY_ID, or add `key_id` to the profile in ~/.stx/credentials."
+        )
+    return ApiKeyCredentials(key_id, private_key, signer=signer)

stx/_version.py

@@ -0,0 +1,12 @@
+"""Package version and the User-Agent sent with every request."""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    __version__ = version("stx-python")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0.0.0+unknown"
+
+USER_AGENT = f"stx-python/{__version__}"