authweave-http-signatures 7.1.2__tar.gz

authweave_http_signatures-7.1.2/.gitignore

@@ -0,0 +1,36 @@
+# macOS
+.DS_Store
+
+# Python bytecode and native build products
+__pycache__/
+*.py[cod]
+*.so
+
+# Local environments and secrets
+/.venv/
+/.uv-cache/
+.env
+.env.*
+!.env.example
+
+# Packaging output
+/build/
+/dist/
+*.egg-info/
+
+# Test, coverage, and tool caches
+.coverage
+.coverage.*
+/coverage.xml
+/htmlcov/
+/.pytest_cache/
+/.ruff_cache/
+/.cache/
+
+# Generated documentation and code intelligence
+/site/
+/docs/_include/
+/.codegraph/
+
+# Docker reference ephemeral key material
+/docker/reference/http-signatures/_runtime/

authweave_http_signatures-7.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladislav Shepilov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

authweave_http_signatures-7.1.2/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: authweave-http-signatures
+Version: 7.1.2
+Summary: Payment HTTP Message Signatures profile for AuthWeave
+Project-URL: homepage, https://github.com/ZYLVEXT/litestar-auth
+Project-URL: documentation, https://zylvext.github.io/litestar-auth/
+Project-URL: source, https://github.com/ZYLVEXT/litestar-auth
+Project-URL: tracker, https://github.com/ZYLVEXT/litestar-auth/issues
+Author-email: Vladislav Shepilov <shepilov.v@protonmail.com>
+Maintainer-email: Vladislav Shepilov <shepilov.v@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: content-digest,http-message-signatures,payments,rfc9421,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: <3.15.0,>=3.12.0
+Requires-Dist: authweave-core==7.1.2
+Requires-Dist: cryptography<51.0,>=50.0.0
+Requires-Dist: http-message-signatures<3.0,>=2.0.1
+Requires-Dist: typing-extensions<5.0,>=4.16.0
+Provides-Extra: litestar
+Requires-Dist: litestar<3.0,>=2.24.0; extra == 'litestar'
+Provides-Extra: redis
+Requires-Dist: redis<9.0,>=8.1.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# authweave-http-signatures
+
+Payment HTTP Message Signatures profile (`authweave-payment-http-sig-v1`)
+for AuthWeave. Verifies RFC 9530 `Content-Digest` and RFC 9421 signatures after
+machine authentication (mTLS or DPoP), then binds `keyid` to the authenticated
+principal and consumes a signature nonce.
+
+This package does **not** authenticate callers and does **not** implement business
+idempotency. Structured Fields parsing uses the maintained
+`http-message-signatures` library (RFC 8941 / RFC 9421).
+
+`PaymentHttpSignatureVerifier(..., observer=...)` emits logical integrity and
+nonce-replay observations through the neutral `authweave-core` observer seam.
+`verify(..., links=(TraceCorrelation(...),))` supports async/retry causality;
+linked trace context never participates in authentication or key binding.
+
+Frozen/custom verifier clocks are request-local; the package does not mutate the
+process-global clock of the Structured Fields/signature implementation.
+
+`sign_payment_message` is a local reference/test helper and accepts an in-process
+`Ed25519PrivateKey`. Production producers keep non-exportable keys in their own KMS/HSM
+signer and emit the same documented RFC 9421 profile outside this verifier package.
+
+```bash
+uv add authweave-http-signatures
+```
+
+See ADR 0004 and `docs/roadmap.md`. Optional extras: `[redis]`, `[litestar]`.

authweave_http_signatures-7.1.2/README.md

@@ -0,0 +1,28 @@
+# authweave-http-signatures
+
+Payment HTTP Message Signatures profile (`authweave-payment-http-sig-v1`)
+for AuthWeave. Verifies RFC 9530 `Content-Digest` and RFC 9421 signatures after
+machine authentication (mTLS or DPoP), then binds `keyid` to the authenticated
+principal and consumes a signature nonce.
+
+This package does **not** authenticate callers and does **not** implement business
+idempotency. Structured Fields parsing uses the maintained
+`http-message-signatures` library (RFC 8941 / RFC 9421).
+
+`PaymentHttpSignatureVerifier(..., observer=...)` emits logical integrity and
+nonce-replay observations through the neutral `authweave-core` observer seam.
+`verify(..., links=(TraceCorrelation(...),))` supports async/retry causality;
+linked trace context never participates in authentication or key binding.
+
+Frozen/custom verifier clocks are request-local; the package does not mutate the
+process-global clock of the Structured Fields/signature implementation.
+
+`sign_payment_message` is a local reference/test helper and accepts an in-process
+`Ed25519PrivateKey`. Production producers keep non-exportable keys in their own KMS/HSM
+signer and emit the same documented RFC 9421 profile outside this verifier package.
+
+```bash
+uv add authweave-http-signatures
+```
+
+See ADR 0004 and `docs/roadmap.md`. Optional extras: `[redis]`, `[litestar]`.

authweave_http_signatures-7.1.2/authweave_http_signatures/__init__.py

@@ -0,0 +1,48 @@
+"""Payment HTTP Message Signatures profile for AuthWeave."""
+
+from authweave_http_signatures.binding import SignatureKeyBinding
+from authweave_http_signatures.digest import CONTENT_DIGEST_SHA256, content_digest_sha256, verify_content_digest
+from authweave_http_signatures.errors import HttpSignatureFailureCode, HttpSignatureVerificationError
+from authweave_http_signatures.models import (
+    DEFAULT_MAX_BODY_BYTES,
+    DEFAULT_MAX_CLOCK_SKEW_SECONDS,
+    DEFAULT_MAX_SIGNATURE_LIFETIME_SECONDS,
+    DEFAULT_NONCE_TTL_SECONDS,
+    JSON_MEDIA_TYPES,
+    PROFILE_TAG,
+    SIGNATURE_LABEL,
+    HttpMessageView,
+    PaymentSignaturePolicy,
+    VerifiedHttpSignature,
+)
+from authweave_http_signatures.nonce import SignatureNonceGuard
+from authweave_http_signatures.proxy_target import UNIX_SOCKET_PROXY, AllowlistedProxyExternalTarget
+from authweave_http_signatures.signer import sign_payment_message
+from authweave_http_signatures.verify import PaymentHttpSignatureVerifier
+
+__version__ = "7.1.2"
+
+__all__ = (
+    "CONTENT_DIGEST_SHA256",
+    "DEFAULT_MAX_BODY_BYTES",
+    "DEFAULT_MAX_CLOCK_SKEW_SECONDS",
+    "DEFAULT_MAX_SIGNATURE_LIFETIME_SECONDS",
+    "DEFAULT_NONCE_TTL_SECONDS",
+    "JSON_MEDIA_TYPES",
+    "PROFILE_TAG",
+    "SIGNATURE_LABEL",
+    "UNIX_SOCKET_PROXY",
+    "AllowlistedProxyExternalTarget",
+    "HttpMessageView",
+    "HttpSignatureFailureCode",
+    "HttpSignatureVerificationError",
+    "PaymentHttpSignatureVerifier",
+    "PaymentSignaturePolicy",
+    "SignatureKeyBinding",
+    "SignatureNonceGuard",
+    "VerifiedHttpSignature",
+    "__version__",
+    "content_digest_sha256",
+    "sign_payment_message",
+    "verify_content_digest",
+)

authweave_http_signatures-7.1.2/authweave_http_signatures/binding.py

@@ -0,0 +1,42 @@
+"""Bind HTTP signature ``keyid`` to an authenticated machine principal."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from authweave_http_signatures.errors import HttpSignatureFailureCode, HttpSignatureVerificationError
+
+if TYPE_CHECKING:
+    from authweave_core import AuthenticationContext
+
+
+@dataclass(frozen=True, slots=True)
+class SignatureKeyBinding:
+    """Exact ownership of one signing key for one authenticated context."""
+
+    key_id: str
+    application_id: str
+    principal_subject: str
+    environment: str
+
+    def __post_init__(self) -> None:
+        """Reject empty binding components."""
+        if not self.key_id or not self.application_id or not self.principal_subject or not self.environment:
+            msg = "signature key binding fields are required"
+            raise ValueError(msg)
+
+    def assert_matches(self, context: AuthenticationContext) -> None:
+        """Fail closed unless ``context`` matches this binding.
+
+        Raises:
+            HttpSignatureVerificationError: On identity mismatch.
+        """
+        evidence = context.evidence
+        application_id = evidence.extensions.get("authweave-workload:application_id")
+        if (
+            context.subject.subject != self.principal_subject
+            or evidence.environment != self.environment
+            or application_id != self.application_id
+        ):
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.KEY_BINDING_MISMATCH)

authweave_http_signatures-7.1.2/authweave_http_signatures/digest.py

@@ -0,0 +1,40 @@
+"""RFC 9530 ``Content-Digest`` helpers for sha-256."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import re
+
+from authweave_http_signatures.errors import HttpSignatureFailureCode, HttpSignatureVerificationError
+
+CONTENT_DIGEST_SHA256 = "sha-256"
+_DIGEST_PATTERN = re.compile(r"^sha-256=:(?P<digest>[A-Za-z0-9+/=]+):$")
+
+
+def content_digest_sha256(body: bytes) -> str:
+    """Return an RFC 9530 ``Content-Digest`` header value for ``body``.
+
+    Returns:
+        ``sha-256=:base64:`` for the exact raw body.
+    """
+    digest = base64.b64encode(hashlib.sha256(body).digest()).decode("ascii")
+    return f"{CONTENT_DIGEST_SHA256}=:{digest}:"
+
+
+def verify_content_digest(*, header_value: str, body: bytes) -> None:
+    """Validate ``Content-Digest`` against the exact raw body.
+
+    Raises:
+        HttpSignatureVerificationError: On malformed or mismatched digests.
+    """
+    match = _DIGEST_PATTERN.fullmatch(header_value.strip())
+    if match is None:
+        raise HttpSignatureVerificationError(HttpSignatureFailureCode.MALFORMED)
+    try:
+        presented = base64.b64decode(match.group("digest"), validate=True)
+    except ValueError as exc:
+        raise HttpSignatureVerificationError(HttpSignatureFailureCode.MALFORMED) from exc
+    expected = hashlib.sha256(body).digest()
+    if len(presented) != len(expected) or presented != expected:
+        raise HttpSignatureVerificationError(HttpSignatureFailureCode.DIGEST_MISMATCH)

authweave_http_signatures-7.1.2/authweave_http_signatures/errors.py

@@ -0,0 +1,37 @@
+"""Typed failure codes for payment HTTP Message Signature verification."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class HttpSignatureFailureCode(StrEnum):
+    """Stable integrity failure codes (secret-free)."""
+
+    MALFORMED = "malformed"
+    BODY_TOO_LARGE = "body_too_large"
+    DIGEST_MISMATCH = "digest_mismatch"
+    CONTENT_TYPE_REJECTED = "content_type_rejected"
+    CONTENT_ENCODING_REJECTED = "content_encoding_rejected"
+    QUERY_REJECTED = "query_rejected"
+    SIGNATURE_INVALID = "signature_invalid"
+    SIGNATURE_EXPIRED = "signature_expired"
+    NOT_YET_VALID = "not_yet_valid"
+    PROFILE_MISMATCH = "profile_mismatch"
+    KEY_BINDING_MISMATCH = "key_binding_mismatch"
+    NONCE_REPLAY = "nonce_replay"
+    STORE_UNAVAILABLE = "store_unavailable"
+    MISSING_COMPONENT = "missing_component"
+
+
+class HttpSignatureVerificationError(Exception):
+    """Fail-closed integrity verification error."""
+
+    def __init__(self, code: HttpSignatureFailureCode) -> None:
+        """Bind a secret-free failure code."""
+        self.code = code
+        super().__init__(code.value)
+
+    def __repr__(self) -> str:
+        """Omit request material from representations."""
+        return f"HttpSignatureVerificationError(code={self.code!r})"

authweave_http_signatures-7.1.2/authweave_http_signatures/litestar_adapter.py

@@ -0,0 +1,44 @@
+"""Litestar helpers for reading an exact raw body before verification."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+from authweave_http_signatures.errors import HttpSignatureFailureCode, HttpSignatureVerificationError
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+
+class _LitestarRequest(Protocol):
+    def stream(self) -> AsyncIterator[bytes]: ...
+
+
+async def read_bounded_raw_body(connection: _LitestarRequest, *, maximum_bytes: int) -> bytes:
+    """Stream the request body up to ``maximum_bytes`` without JSON parsing.
+
+    Returns:
+        The exact raw body bytes.
+
+    Raises:
+        HttpSignatureVerificationError: If the body is incomplete or too large.
+    """
+    if maximum_bytes <= 0:
+        msg = "maximum_bytes must be positive"
+        raise ValueError(msg)
+    chunks: list[bytes] = []
+    total = 0
+    oversized = False
+    stream: AsyncIterator[bytes] = connection.stream()
+    try:
+        async for chunk in stream:
+            total += len(chunk)
+            if total > maximum_bytes:
+                oversized = True
+                break
+            chunks.append(chunk)
+    except Exception as exc:
+        raise HttpSignatureVerificationError(HttpSignatureFailureCode.MALFORMED) from exc
+    if oversized:
+        raise HttpSignatureVerificationError(HttpSignatureFailureCode.BODY_TOO_LARGE)
+    return b"".join(chunks)

authweave_http_signatures-7.1.2/authweave_http_signatures/models.py

@@ -0,0 +1,128 @@
+"""Immutable HTTP message view and payment signature policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Final
+
+PROFILE_TAG: Final = "authweave-payment-http-sig-v1"
+SIGNATURE_LABEL: Final = "payment"
+DEFAULT_MAX_BODY_BYTES: Final = 262_144
+DEFAULT_MAX_CLOCK_SKEW_SECONDS: Final = 30
+DEFAULT_MAX_SIGNATURE_LIFETIME_SECONDS: Final = 300
+DEFAULT_NONCE_TTL_SECONDS: Final = 600
+JSON_MEDIA_TYPES: Final = frozenset({"application/json", "application/json; charset=utf-8"})
+
+_COVERED_BASE: Final = ("@method", "@target-uri", "content-digest", "content-type", "idempotency-key")
+_COVERED_DPOP: Final = (*_COVERED_BASE, "authorization")
+
+
+@dataclass(frozen=True, slots=True)
+class HttpMessageView:
+    """Exact raw HTTP request projection used for digest and signature checks."""
+
+    method: str
+    target_uri: str = field(repr=False)
+    headers: tuple[tuple[str, str], ...] = field(default=(), repr=False)
+    body: bytes = field(default=b"", repr=False)
+
+    def __post_init__(self) -> None:
+        """Reject empty method/target or oversized metadata."""
+        if not self.method or not self.method.isascii() or any(ch.isspace() for ch in self.method):
+            msg = "method must be non-empty printable ASCII without whitespace"
+            raise ValueError(msg)
+        if not self.target_uri or not self.target_uri.startswith("https://"):
+            msg = "target_uri must be an absolute https URI"
+            raise ValueError(msg)
+        if len(self.body) > DEFAULT_MAX_BODY_BYTES * 2:
+            msg = "body exceeds absolute safety ceiling"
+            raise ValueError(msg)
+
+    def header(self, name: str) -> str | None:
+        """Return the single value for ``name`` (case-insensitive) or ``None``.
+
+        Returns:
+            The header value when present exactly once.
+        """
+        needle = name.lower()
+        matches = [value for header, value in self.headers if header.lower() == needle]
+        if len(matches) > 1:
+            msg = f"duplicate header: {name}"
+            raise ValueError(msg)
+        return matches[0] if matches else None
+
+    def headers_dict(self) -> dict[str, str]:
+        """Return a case-preserving single-value header mapping.
+
+        Returns:
+            Header name to value.
+
+        Raises:
+            ValueError: If any header name is duplicated.
+        """
+        result: dict[str, str] = {}
+        for name, value in self.headers:
+            key = name.lower()
+            if key in {item.lower() for item in result}:
+                msg = f"duplicate header: {name}"
+                raise ValueError(msg)
+            result[name] = value
+        return result
+
+
+@dataclass(frozen=True, slots=True)
+class PaymentSignaturePolicy:
+    """Exact payment HTTP signature profile v1 policy."""
+
+    require_authorization_component: bool = False
+    allow_query: bool = False
+    max_body_bytes: int = DEFAULT_MAX_BODY_BYTES
+    max_clock_skew_seconds: int = DEFAULT_MAX_CLOCK_SKEW_SECONDS
+    max_signature_lifetime_seconds: int = DEFAULT_MAX_SIGNATURE_LIFETIME_SECONDS
+    nonce_ttl_seconds: int = DEFAULT_NONCE_TTL_SECONDS
+    json_media_types: frozenset[str] = field(default_factory=lambda: JSON_MEDIA_TYPES)
+    profile_tag: str = PROFILE_TAG
+    signature_label: str = SIGNATURE_LABEL
+
+    def __post_init__(self) -> None:
+        """Reject non-positive bounds or empty profile identity."""
+        if self.max_body_bytes <= 0 or self.max_clock_skew_seconds < 0:
+            msg = "body/clock policy is invalid"
+            raise ValueError(msg)
+        if self.max_signature_lifetime_seconds <= 0 or self.nonce_ttl_seconds <= 0:
+            msg = "lifetime policy is invalid"
+            raise ValueError(msg)
+        if not self.profile_tag or not self.signature_label or not self.json_media_types:
+            msg = "profile identity and media types are required"
+            raise ValueError(msg)
+
+    @property
+    def covered_components(self) -> tuple[str, ...]:
+        """The exact covered-component list for this route variant.
+
+        Returns:
+            Covered component identifiers in profile order.
+        """
+        return _COVERED_DPOP if self.require_authorization_component else _COVERED_BASE
+
+
+@dataclass(frozen=True, slots=True)
+class VerifiedHttpSignature:
+    """Secret-free result after digest, signature, binding, and nonce checks."""
+
+    key_id: str
+    nonce: str
+    profile_tag: str
+    created: int
+    expires: int
+    idempotency_key: str
+    content_type: str
+    body: bytes
+
+    def __repr__(self) -> str:
+        """Omit raw body bytes from representations."""
+        return (
+            "VerifiedHttpSignature("
+            f"key_id={self.key_id!r}, nonce=..., profile_tag={self.profile_tag!r}, "
+            f"idempotency_key={self.idempotency_key!r})"
+        )

authweave_http_signatures-7.1.2/authweave_http_signatures/nonce.py

@@ -0,0 +1,52 @@
+"""Signature nonce replay guard (not business idempotency)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from authweave_core import ReplayOutcome, SecurityOperation, SecurityOutcome, observe_security
+
+from authweave_http_signatures.errors import HttpSignatureFailureCode, HttpSignatureVerificationError
+
+if TYPE_CHECKING:
+    from authweave_core import ReplayStore, SecurityObserver
+
+
+class SignatureNonceGuard:
+    """Consume one signature nonce exactly once per profile/key namespace."""
+
+    __slots__ = ("_profile_tag", "_store", "_ttl_seconds")
+
+    def __init__(self, store: ReplayStore, *, profile_tag: str, ttl_seconds: float) -> None:
+        """Bind the replay store and profile namespace."""
+        if ttl_seconds <= 0 or not profile_tag:
+            msg = "nonce guard requires positive ttl and profile_tag"
+            raise ValueError(msg)
+        self._store = store
+        self._profile_tag = profile_tag
+        self._ttl_seconds = ttl_seconds
+
+    async def consume(self, *, key_id: str, nonce: str, observer: SecurityObserver | None = None) -> None:
+        """Record ``nonce`` for ``key_id`` or raise on replay/outage.
+
+        Raises:
+            HttpSignatureVerificationError: Mapped from the replay store outcome.
+        """
+        if not key_id or not nonce:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.MALFORMED)
+        key = f"http-sig:{self._profile_tag}:{key_id}:{nonce}"
+        with observe_security(observer, SecurityOperation.REPLAY_CHECK, profile=self._profile_tag) as observation:
+            outcome = await self._store.check_and_store(key, ttl_seconds=self._ttl_seconds)
+            if outcome is ReplayOutcome.STORED:
+                observation.set_outcome(SecurityOutcome.STORED)
+            elif outcome is ReplayOutcome.REPLAY:
+                observation.set_outcome(SecurityOutcome.REPLAY)
+            elif outcome is ReplayOutcome.CAPACITY_EXCEEDED:
+                observation.set_outcome(SecurityOutcome.CAPACITY_EXCEEDED)
+            else:
+                observation.set_outcome(SecurityOutcome.UNAVAILABLE)
+        if outcome is ReplayOutcome.STORED:
+            return
+        if outcome is ReplayOutcome.REPLAY:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.NONCE_REPLAY)
+        raise HttpSignatureVerificationError(HttpSignatureFailureCode.STORE_UNAVAILABLE)

authweave_http_signatures-7.1.2/authweave_http_signatures/proxy_target.py

@@ -0,0 +1,85 @@
+"""Allowlisted reverse-proxy projection of the external HTTPS request target."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from urllib.parse import urlsplit
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from typing import Any
+
+UNIX_SOCKET_PROXY = "unix"
+_DEFAULT_HEADER = b"x-auth-external-target"
+
+
+@dataclass(frozen=True, slots=True)
+class AllowlistedProxyExternalTarget:
+    """Project ``target_uri`` only from an allowlisted proxy identity header.
+
+    Client-controlled ``Host`` / ``Forwarded`` are ignored. The proxy must strip
+    and re-inject ``x-auth-external-target`` (ADR 0005).
+    """
+
+    proxy_addresses: frozenset[str]
+    header_name: bytes = _DEFAULT_HEADER
+
+    def __post_init__(self) -> None:
+        """Require a non-empty proxy allowlist and header name."""
+        if not self.proxy_addresses or not self.header_name:
+            msg = "proxy addresses and header name are required"
+            raise ValueError(msg)
+
+    def __call__(self, scope: Mapping[str, Any]) -> str | None:
+        """Return the absolute HTTPS target or ``None`` when absent.
+
+        Raises:
+            ValueError: If the proxy is untrusted or the header is ambiguous/malformed.
+        """
+        values = _header_values(scope, self.header_name)
+        if not values:
+            return None
+        client_address = _client_address(scope)
+        if client_address not in self.proxy_addresses:
+            msg = "external request target is not trusted"
+            raise ValueError(msg)
+        if len(values) != 1:
+            msg = "external request target is ambiguous"
+            raise ValueError(msg)
+        try:
+            target = values[0].decode("ascii")
+        except UnicodeDecodeError as exc:
+            msg = "external request target is invalid"
+            raise ValueError(msg) from exc
+        _validate_https_target(target)
+        return target
+
+
+def _client_address(scope: Mapping[str, Any]) -> str | None:
+    client = scope.get("client")
+    if client is None:
+        return UNIX_SOCKET_PROXY
+    if isinstance(client, tuple) and client and isinstance(client[0], str):
+        # Uvicorn/ASGI often reports an empty host for Unix-domain peers.
+        return UNIX_SOCKET_PROXY if client[0] in {"", UNIX_SOCKET_PROXY} else client[0]
+    return None
+
+
+def _header_values(scope: Mapping[str, Any], name: bytes) -> list[bytes]:
+    wanted = name.lower()
+    found: list[bytes] = []
+    for raw_name, value in scope.get("headers", ()):
+        if raw_name.lower() == wanted:
+            found.append(value)
+    return found
+
+
+def _validate_https_target(target: str) -> None:
+    parts = urlsplit(target)
+    if parts.scheme != "https" or not parts.netloc or parts.fragment or parts.username or parts.password:
+        msg = "external request target must be an absolute https URL"
+        raise ValueError(msg)
+
+
+__all__ = ("UNIX_SOCKET_PROXY", "AllowlistedProxyExternalTarget")

authweave_http_signatures-7.1.2/authweave_http_signatures/redis_store.py

@@ -0,0 +1,42 @@
+"""Optional Redis-backed signature nonce replay store."""
+
+from __future__ import annotations
+
+from authweave_core import ReplayOutcome, validate_replay_key
+
+
+class RedisHttpSignatureReplayStore:
+    """Thin Redis SET NX EX adapter for HTTP signature nonces.
+
+    Requires the ``authweave-http-signatures[redis]`` extra.
+    """
+
+    __slots__ = ("_redis",)
+
+    def __init__(self, redis: object) -> None:
+        """Bind an async Redis client exposing ``set(..., nx=True, ex=...)``."""
+        self._redis = redis
+
+    async def check_and_store(self, key: str, *, ttl_seconds: float) -> ReplayOutcome:
+        """Atomically claim ``key`` with a TTL.
+
+        Returns:
+            The typed put-if-absent outcome.
+
+        Raises:
+            ValueError: If the key or TTL is invalid.
+        """
+        validate_replay_key(key)
+        if ttl_seconds <= 0:
+            msg = "ttl_seconds must be positive"
+            raise ValueError(msg)
+        try:
+            created = await self._redis.set(  # ty: ignore[unresolved-attribute]
+                key,
+                "1",
+                nx=True,
+                ex=max(1, int(ttl_seconds)),
+            )
+        except Exception:  # ruff: ignore[blind-except] - transport failures are Unavailable
+            return ReplayOutcome.UNAVAILABLE
+        return ReplayOutcome.STORED if created else ReplayOutcome.REPLAY

authweave_http_signatures-7.1.2/authweave_http_signatures/signer.py

@@ -0,0 +1,94 @@
+"""Local Ed25519 payment-message signing helper."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from http_message_signatures import HTTPMessageSigner, HTTPSignatureKeyResolver, algorithms
+
+from authweave_http_signatures.digest import content_digest_sha256
+from authweave_http_signatures.models import HttpMessageView, PaymentSignaturePolicy
+
+
+@dataclass
+class _MessageAdapter:
+    """Minimal request shape accepted by ``http-message-signatures``."""
+
+    method: str
+    url: str = field(repr=False)
+    headers: dict[str, str] = field(repr=False)
+
+
+class _KeyResolver(HTTPSignatureKeyResolver):
+    def __init__(self, keys: dict[str, Ed25519PrivateKey]) -> None:
+        self._keys = keys
+
+    def resolve_private_key(self, key_id: str) -> Ed25519PrivateKey:
+        return self._keys[key_id]
+
+    def resolve_public_key(self, key_id: str) -> object:
+        return self._keys[key_id].public_key()
+
+
+def sign_payment_message(
+    *,
+    view: HttpMessageView,
+    policy: PaymentSignaturePolicy,
+    key_id: str,
+    private_key: Ed25519PrivateKey,
+    nonce: str,
+    now: datetime | None = None,
+    lifetime: timedelta | None = None,
+) -> HttpMessageView:
+    """Attach profile-v1 digest and signature headers with a local private key.
+
+    This reference helper is for tests and in-process signers. Production KMS/HSM
+    integrations should construct the same RFC 9421 profile outside AuthWeave so
+    private key material remains non-exportable.
+
+    Returns:
+        A new ``HttpMessageView`` with digest and signature headers applied.
+
+    Raises:
+        ValueError: If required application headers are missing.
+    """
+    created = now or datetime.now(UTC)
+    signature_lifetime = timedelta(seconds=policy.max_signature_lifetime_seconds) if lifetime is None else lifetime
+    if not timedelta(0) < signature_lifetime <= timedelta(seconds=policy.max_signature_lifetime_seconds):
+        msg = "signature lifetime is invalid"
+        raise ValueError(msg)
+    expires = created + signature_lifetime
+    headers = dict(view.headers_dict())
+    headers["content-digest"] = content_digest_sha256(view.body)
+    if "content-type" not in {name.lower() for name in headers}:
+        msg = "content-type is required"
+        raise ValueError(msg)
+    if "idempotency-key" not in {name.lower() for name in headers}:
+        msg = "idempotency-key is required"
+        raise ValueError(msg)
+    if policy.require_authorization_component and "authorization" not in {name.lower() for name in headers}:
+        msg = "authorization is required for DPoP variant"
+        raise ValueError(msg)
+    # Canonical lowercase names for covered components.
+    normalized = {name.lower(): value for name, value in headers.items()}
+    adapter = _MessageAdapter(method=view.method, url=view.target_uri, headers=normalized)
+    signer = HTTPMessageSigner(
+        signature_algorithm=algorithms.ED25519,
+        key_resolver=_KeyResolver({key_id: private_key}),
+    )
+    signer.sign(
+        adapter,
+        key_id=key_id,
+        created=created,
+        expires=expires,
+        nonce=nonce,
+        label=policy.signature_label,
+        tag=policy.profile_tag,
+        covered_component_ids=list(policy.covered_components),
+        include_alg=True,
+    )
+    # Reconstruct header tuple preserving signature headers from the adapter.
+    final_headers = tuple((name, value) for name, value in adapter.headers.items())
+    return HttpMessageView(method=view.method, target_uri=view.target_uri, headers=final_headers, body=view.body)

authweave_http_signatures-7.1.2/authweave_http_signatures/verify.py

@@ -0,0 +1,281 @@
+"""Payment HTTP Message Signature verifier."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlsplit
+
+from authweave_core import SecurityOperation, SecurityOutcome, observe_security
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from http_message_signatures import (
+    HTTPMessageVerifier,
+    HTTPSignatureKeyResolver,
+    InvalidSignature,
+    algorithms,
+    http_sfv,
+)
+from http_message_signatures.structures import CaseInsensitiveDict
+
+from authweave_http_signatures.digest import verify_content_digest
+from authweave_http_signatures.errors import HttpSignatureFailureCode, HttpSignatureVerificationError
+from authweave_http_signatures.models import VerifiedHttpSignature
+
+if TYPE_CHECKING:
+    from authweave_core import AuthenticationContext, SecurityObserver, TraceCorrelation
+
+    from authweave_http_signatures.binding import SignatureKeyBinding
+    from authweave_http_signatures.models import HttpMessageView, PaymentSignaturePolicy
+    from authweave_http_signatures.nonce import SignatureNonceGuard
+
+
+@dataclass
+class _MessageAdapter:
+    method: str
+    url: str = field(repr=False)
+    headers: Mapping[str, str] = field(repr=False)
+
+
+class _PublicKeyResolver(HTTPSignatureKeyResolver):
+    def __init__(self, keys: Mapping[str, Ed25519PublicKey]) -> None:
+        self._keys = keys
+
+    def resolve_public_key(self, key_id: str) -> Ed25519PublicKey:
+        try:
+            return self._keys[key_id]
+        except KeyError as exc:
+            msg = "unknown key id"
+            raise KeyError(msg) from exc
+
+    def resolve_private_key(self, key_id: str) -> Ed25519PublicKey:
+        raise KeyError(key_id)
+
+
+class _ProfileHTTPMessageVerifier(HTTPMessageVerifier):
+    """Delegate parsing/crypto while AuthWeave owns request-local time policy."""
+
+    def validate_created_and_expires(
+        self,
+        sig_input: Any,
+        max_age: timedelta | None = None,
+    ) -> None:
+        """Skip the upstream process-global wall clock check.
+
+        AuthWeave validates required ``created``/``expires``, lifetime, expiry,
+        future time, and configured skew immediately after signature verification.
+        """
+        _ = self, sig_input, max_age
+
+
+class PaymentHttpSignatureVerifier:
+    """Verify Content-Digest + RFC 9421 signature for profile v1."""
+
+    __slots__ = ("_bindings", "_nonce_guard", "_observer", "_policy", "_public_keys", "_time_source")
+
+    def __init__(
+        self,
+        *,
+        policy: PaymentSignaturePolicy,
+        public_keys: Mapping[str, Ed25519PublicKey],
+        bindings: Mapping[str, SignatureKeyBinding],
+        nonce_guard: SignatureNonceGuard,
+        time_source: Callable[[], datetime] | None = None,
+        observer: SecurityObserver | None = None,
+    ) -> None:
+        """Bind profile policy, public keys, ownership, and nonce store."""
+        if not public_keys or not bindings:
+            msg = "public keys and bindings are required"
+            raise ValueError(msg)
+        self._policy = policy
+        self._public_keys = dict(public_keys)
+        self._bindings = dict(bindings)
+        self._nonce_guard = nonce_guard
+        self._time_source = time_source or (lambda: datetime.now(UTC))
+        self._observer = observer
+
+    async def verify(
+        self,
+        view: HttpMessageView,
+        *,
+        context: AuthenticationContext,
+        links: Sequence[TraceCorrelation] = (),
+    ) -> VerifiedHttpSignature:
+        """Verify digest, signature, key binding, and nonce fail-closed.
+
+        Returns:
+            A secret-free verified integrity envelope retaining the exact body.
+
+        Raises:
+            HttpSignatureVerificationError: On any integrity failure.
+        """
+        with observe_security(
+            self._observer,
+            SecurityOperation.VERIFY_HTTP_SIGNATURE,
+            profile=self._policy.profile_tag,
+            credential_kind="http_message_signature",
+            links=links,
+        ) as observation:
+            try:
+                result = await self._verify(view, context=context)
+            except HttpSignatureVerificationError as exc:
+                outcome = (
+                    SecurityOutcome.UNAVAILABLE
+                    if exc.code is HttpSignatureFailureCode.STORE_UNAVAILABLE
+                    else SecurityOutcome.INVALID
+                )
+                observation.set_outcome(outcome, reason_code=exc.code.value)
+                raise
+            observation.set_outcome(SecurityOutcome.VERIFIED)
+            return result
+
+    async def _verify(self, view: HttpMessageView, *, context: AuthenticationContext) -> VerifiedHttpSignature:
+        self._check_body_and_encoding(view)
+        self._check_query(view.target_uri)
+        content_type = self._require_header(view, "content-type")
+        if content_type.lower() not in {item.lower() for item in self._policy.json_media_types}:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.CONTENT_TYPE_REJECTED)
+        idempotency_key = self._require_header(view, "idempotency-key")
+        digest = self._require_header(view, "content-digest")
+        verify_content_digest(header_value=digest, body=view.body)
+        if self._policy.require_authorization_component:
+            self._require_header(view, "authorization")
+        signature_input = self._require_header(view, "signature-input")
+        signature = self._require_header(view, "signature")
+        self._assert_single_profile_signature(signature_input=signature_input, signature=signature)
+        headers = CaseInsensitiveDict(dict(view.headers_dict().items()))
+        adapter = _MessageAdapter(method=view.method, url=view.target_uri, headers=headers)
+        verifier = _ProfileHTTPMessageVerifier(
+            signature_algorithm=algorithms.ED25519,
+            key_resolver=_PublicKeyResolver(self._public_keys),
+        )
+        try:
+            results = verifier.verify(
+                adapter,
+                max_age=timedelta(seconds=self._policy.max_signature_lifetime_seconds),
+                expect_tag=self._policy.profile_tag,
+                expect_label=self._policy.signature_label,
+            )
+        except InvalidSignature as exc:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.SIGNATURE_INVALID) from exc
+        except Exception as exc:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.MALFORMED) from exc
+        if len(results) != 1:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.MALFORMED)
+        result = results[0]
+        params = dict(result.parameters)
+        key_id = params.get("keyid")
+        nonce = params.get("nonce")
+        created = params.get("created")
+        expires = params.get("expires")
+        tag = params.get("tag")
+        if not isinstance(key_id, str) or not isinstance(nonce, str) or tag != self._policy.profile_tag:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.PROFILE_MISMATCH)
+        created_i = _structured_field_integer(created)
+        expires_i = _structured_field_integer(expires)
+        if created_i is None or expires_i is None:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.MALFORMED)
+        now = int(self._time_source().timestamp())
+        if created_i > now + self._policy.max_clock_skew_seconds:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.NOT_YET_VALID)
+        if expires_i <= now - self._policy.max_clock_skew_seconds:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.SIGNATURE_EXPIRED)
+        if expires_i <= created_i or expires_i - created_i > self._policy.max_signature_lifetime_seconds:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.MALFORMED)
+        covered = tuple(
+            key.strip('"') for key in result.covered_components if str(key).strip('"') != "@signature-params"
+        )
+        if covered != self._policy.covered_components:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.PROFILE_MISMATCH)
+        binding = self._bindings.get(key_id)
+        if binding is None:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.KEY_BINDING_MISMATCH)
+        binding.assert_matches(context)
+        await self._nonce_guard.consume(key_id=key_id, nonce=nonce, observer=self._observer)
+        return VerifiedHttpSignature(
+            key_id=key_id,
+            nonce=nonce,
+            profile_tag=self._policy.profile_tag,
+            created=created_i,
+            expires=expires_i,
+            idempotency_key=idempotency_key,
+            content_type=content_type,
+            body=view.body,
+        )
+
+    def _check_body_and_encoding(self, view: HttpMessageView) -> None:
+        if len(view.body) > self._policy.max_body_bytes:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.BODY_TOO_LARGE)
+        encoding = view.header("content-encoding")
+        if encoding is not None and encoding.lower() not in {"", "identity"}:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.CONTENT_ENCODING_REJECTED)
+
+    def _check_query(self, target_uri: str) -> None:
+        if self._policy.allow_query:
+            return
+        if urlsplit(target_uri).query:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.QUERY_REJECTED)
+
+    def _assert_single_profile_signature(self, *, signature_input: str, signature: str) -> None:
+        """Require exactly one SF dictionary member equal to the profile label.
+
+        Upstream parsers collapse duplicate keys; count top-level members so
+        ``label=..., label=...`` cannot silently overwrite.
+        """
+        label = self._policy.signature_label
+        if _sf_dictionary_member_count(signature_input) != 1 or _sf_dictionary_member_count(signature) != 1:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.MALFORMED)
+        try:
+            input_node = http_sfv.Dictionary()
+            input_node.parse(signature_input.encode("ascii"))
+            signature_node = http_sfv.Dictionary()
+            signature_node.parse(signature.encode("ascii"))
+        except Exception as exc:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.MALFORMED) from exc
+        if list(input_node.keys()) != [label] or list(signature_node.keys()) != [label]:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.PROFILE_MISMATCH)
+
+    @staticmethod
+    def _require_header(view: HttpMessageView, name: str) -> str:
+        try:
+            value = view.header(name)
+        except ValueError as exc:
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.MALFORMED) from exc
+        if value is None or not value.strip():
+            raise HttpSignatureVerificationError(HttpSignatureFailureCode.MISSING_COMPONENT)
+        return value
+
+
+def _sf_dictionary_member_count(raw: str) -> int:
+    """Count RFC 8941 dictionary members separated by top-level commas."""
+    text = raw.strip()
+    if not text:
+        return 0
+    depth = 0
+    in_string = False
+    escape = False
+    members = 1
+    for char in text:
+        if in_string:
+            if escape:
+                escape = False
+            elif char == "\\":
+                escape = True
+            elif char == '"':
+                in_string = False
+            continue
+        if char == '"':
+            in_string = True
+        elif char == "(":
+            depth += 1
+        elif char == ")" and depth:
+            depth -= 1
+        elif char == "," and depth == 0:
+            members += 1
+    return members
+
+
+def _structured_field_integer(value: object) -> int | None:
+    """Accept only RFC 8941 Integer values, excluding Python ``bool``."""
+    return value if isinstance(value, int) and not isinstance(value, bool) else None

authweave_http_signatures-7.1.2/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "authweave-http-signatures"
+version = "7.1.2"
+description = "Payment HTTP Message Signatures profile for AuthWeave"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Vladislav Shepilov", email = "shepilov.v@protonmail.com"},
+]
+maintainers = [
+    {name = "Vladislav Shepilov", email = "shepilov.v@protonmail.com"},
+]
+keywords = ["http-message-signatures", "rfc9421", "content-digest", "payments", "security"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+requires-python = "<3.15.0,>=3.12.0"
+dependencies = [
+    "authweave-core==7.1.2",
+    "cryptography>=50.0.0,<51.0",
+    "http-message-signatures>=2.0.1,<3.0",
+    "typing-extensions>=4.16.0,<5.0",
+]
+
+[project.optional-dependencies]
+redis = ["redis>=8.1.0,<9.0"]
+litestar = ["litestar>=2.24.0,<3.0"]
+
+[project.urls]
+homepage = "https://github.com/ZYLVEXT/litestar-auth"
+documentation = "https://zylvext.github.io/litestar-auth/"
+source = "https://github.com/ZYLVEXT/litestar-auth"
+tracker = "https://github.com/ZYLVEXT/litestar-auth/issues"
+
+[build-system]
+requires = ["hatchling==1.31.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["authweave_http_signatures"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["authweave_http_signatures"]
+
+[tool.coverage.run]
+source = ["authweave_http_signatures"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+
+[tool.ty.environment]
+python-version = "3.12"
+
+[tool.ty.src]
+include = ["authweave_http_signatures", "tests"]
+
+[tool.deptry]
+experimental_namespace_package = true
+
+[tool.deptry.per_rule_ignores]
+# http-message-signatures 2.0.1 vendors http_sfv code that imports typing_extensions but omits it
+# from Requires-Dist; keep the direct dependency until upstream metadata includes it.
+DEP002 = ["litestar", "redis", "typing-extensions"]
+
+[tool.uv.sources]
+authweave-core = {workspace = true}