seampact-signed-webhooks 1.0.0__tar.gz

seampact_signed_webhooks-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/

seampact_signed_webhooks-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Metral
+
+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.

seampact_signed_webhooks-1.0.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.5
+Name: seampact-signed-webhooks
+Version: 1.0.0
+Summary: Verifies a template-signed webhook (HMAC, timestamp tolerance, secret rotation) inside an authenticate hook.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+The template signature verifier an authenticate hook calls for a signed identity (ADR 0013), for Python apps.

seampact_signed_webhooks-1.0.0/README.md

@@ -0,0 +1 @@
+The template signature verifier an authenticate hook calls for a signed identity (ADR 0013), for Python apps.

seampact_signed_webhooks-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "seampact-signed-webhooks"
+version = "1.0.0"
+description = "Verifies a template-signed webhook (HMAC, timestamp tolerance, secret rotation) inside an authenticate hook."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
+]
+
+# PEP 420: `seampact` is a namespace shared by every seampact distribution, so it has no `__init__.py`.
+[tool.hatch.build.targets.wheel]
+packages = ["src/seampact"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/seampact", "LICENSE"]

seampact_signed_webhooks-1.0.0/src/seampact/signed_webhooks/__init__.py

@@ -0,0 +1,35 @@
+"""The template signature verifier an authenticate hook calls for a signed identity (ADR 0013).
+
+HMAC over the raw body, timestamp tolerance and secret rotation; the application keeps its secrets.
+"""
+
+from seampact.signed_webhooks.clock import Clock, SystemClock
+from seampact.signed_webhooks.placeholders import SUPPORTED_ALGORITHM
+from seampact.signed_webhooks.refusals import (
+    EmptySignatureSecretError,
+    SignaturePayloadInvalidError,
+    SignatureToleranceInvalidError,
+    UnsupportedSignatureAlgorithmError,
+)
+from seampact.signed_webhooks.scheme import SignatureEncoding, SignatureScheme
+from seampact.signed_webhooks.secret_lookup import SecretLookup
+from seampact.signed_webhooks.signed_message import SignedMessage
+from seampact.signed_webhooks.verification import SignatureFailure, SignatureVerification
+from seampact.signed_webhooks.verifier import TemplateSignatureVerifier
+
+__all__ = [
+    "SUPPORTED_ALGORITHM",
+    "Clock",
+    "EmptySignatureSecretError",
+    "SecretLookup",
+    "SignatureEncoding",
+    "SignatureFailure",
+    "SignaturePayloadInvalidError",
+    "SignatureScheme",
+    "SignatureToleranceInvalidError",
+    "SignatureVerification",
+    "SignedMessage",
+    "SystemClock",
+    "TemplateSignatureVerifier",
+    "UnsupportedSignatureAlgorithmError",
+]

seampact_signed_webhooks-1.0.0/src/seampact/signed_webhooks/clock.py

@@ -0,0 +1,19 @@
+"""The clock the timestamp tolerance is checked against: the system clock, or a fixed one in a test."""
+
+import time
+from typing import Final, Protocol
+
+_NANOSECONDS_PER_MILLISECOND: Final = 1_000_000
+
+
+class Clock(Protocol):
+    def now_milliseconds(self) -> int:
+        """Milliseconds since the Unix epoch."""
+        ...
+
+
+class SystemClock:
+    """The system clock."""
+
+    def now_milliseconds(self) -> int:
+        return time.time_ns() // _NANOSECONDS_PER_MILLISECOND

seampact_signed_webhooks-1.0.0/src/seampact/signed_webhooks/placeholders.py

@@ -0,0 +1,9 @@
+"""The constants of a template signature scheme: the placeholders of its payload and the one algorithm computed."""
+
+from typing import Final
+
+# The only MAC this verifier computes; the IR enum is open, so another algorithm is refused by name.
+SUPPORTED_ALGORITHM: Final = "hmac-sha256"
+
+TIMESTAMP_PLACEHOLDER: Final = "{ts}"
+RAW_BODY_PLACEHOLDER: Final = "{rawBody}"

seampact_signed_webhooks-1.0.0/src/seampact/signed_webhooks/refusals.py

@@ -0,0 +1,78 @@
+"""The refusals of the verifier: a scheme or a secret it cannot check safely, each with a stable code."""
+
+from typing import ClassVar, Self
+
+from seampact.signed_webhooks.placeholders import SUPPORTED_ALGORITHM
+
+
+class UnsupportedSignatureAlgorithmError(ValueError):
+    """The scheme names an algorithm this verifier does not compute: a contract it cannot verify."""
+
+    CODE: ClassVar[str] = "signature.algorithm.unsupported"
+
+    def __init__(self, algorithm: str) -> None:
+        super().__init__(
+            f"The signature algorithm '{algorithm}' is not one seampact-signed-webhooks computes; it computes "
+            f"'{SUPPORTED_ALGORITHM}'. Verify this scheme with 'verify: application', or update the package to a "
+            "release that computes it."
+        )
+        self.algorithm = algorithm
+
+
+class SignaturePayloadInvalidError(ValueError):
+    """The signed payload does not hold `{rawBody}` exactly once and `{ts}` at most once."""
+
+    CODE: ClassVar[str] = "signature.payload.invalid"
+
+    def __init__(self, payload: str) -> None:
+        super().__init__(
+            f"The signed payload '{payload}' must hold {{rawBody}} exactly once and {{ts}} at most once, or a "
+            "captured signature could pass with another body. Copy the payload of the hook's signature template."
+        )
+        self.payload = payload
+
+
+class SignatureToleranceInvalidError(ValueError):
+    """The tolerance does not fit the payload: missing for a `{ts}` payload, negative, or given without `{ts}`."""
+
+    CODE: ClassVar[str] = "signature.tolerance.invalid"
+
+    @classmethod
+    def missing(cls, payload: str) -> Self:
+        return cls(
+            f"The signed payload '{payload}' holds {{ts}} but the scheme has no tolerance, so a replayed request of "
+            "any age would pass. Pass the tolerance of the hook's signature template as tolerance_ms."
+        )
+
+    @classmethod
+    def not_whole_milliseconds(cls, tolerance_ms: object) -> Self:
+        return cls(
+            f"The tolerance {tolerance_ms!r} ms is not a whole number of milliseconds of at least 0, so the "
+            "timestamp check would not hold. Pass the tolerance of the hook's signature template as tolerance_ms."
+        )
+
+    @classmethod
+    def without_timestamp(cls, payload: str) -> Self:
+        return cls(
+            f"The scheme has a tolerance but its signed payload '{payload}' holds no {{ts}}, so there is no "
+            "timestamp to check. Drop the tolerance, as the hook's signature template does."
+        )
+
+
+class EmptySignatureSecretError(ValueError):
+    """The lookup returned an empty secret, one that is neither text nor bytes, or text that does not encode as UTF-8:
+    no MAC can be computed safely with it.
+
+    The message names the key id and the position in the list, never a secret.
+    """
+
+    CODE: ClassVar[str] = "signature.secret.empty"
+
+    def __init__(self, key_id: str, index: int) -> None:
+        super().__init__(
+            f"The secret at position {index} looked up for the key '{key_id}' is empty, neither text nor bytes, or "
+            "text that does not encode as UTF-8, so no request can be verified safely with it. Configure the secret "
+            "(check the environment variable behind the lookup)."
+        )
+        self.key_id = key_id
+        self.index = index

seampact_signed_webhooks-1.0.0/src/seampact/signed_webhooks/scheme.py

@@ -0,0 +1,59 @@
+"""A template signature scheme (ADR 0013): the MAC algorithm, the signed payload, the encoding and the tolerance."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from seampact.signed_webhooks.placeholders import RAW_BODY_PLACEHOLDER, TIMESTAMP_PLACEHOLDER
+from seampact.signed_webhooks.refusals import SignaturePayloadInvalidError, SignatureToleranceInvalidError
+
+
+class SignatureEncoding(StrEnum):
+    """How a signature scheme writes its MAC in the header."""
+
+    HEX = "hex"
+    BASE64 = "base64"
+
+
+@dataclass(frozen=True, slots=True)
+class SignatureScheme:
+    """The scheme the application copies from the hook's signature template, tolerance included.
+
+    Raises `SignaturePayloadInvalidError` when the payload does not hold `{rawBody}` exactly once and `{ts}` at most
+    once, and `SignatureToleranceInvalidError` when the tolerance is missing for a `{ts}` payload, is not a whole
+    number of milliseconds of at least 0, or is given for a payload with no `{ts}`.
+    """
+
+    algorithm: str
+    payload: str
+    encoding: SignatureEncoding
+    tolerance_ms: int | None = None
+
+    def __post_init__(self) -> None:
+        # A plain "hex" or "base64" becomes the enum member; any other text raises the enum's ValueError.
+        object.__setattr__(self, "encoding", SignatureEncoding(self.encoding))
+
+        timestamp_count = self.payload.count(TIMESTAMP_PLACEHOLDER)
+
+        if self.payload.count(RAW_BODY_PLACEHOLDER) != 1 or timestamp_count > 1:
+            raise SignaturePayloadInvalidError(self.payload)
+
+        _refuse_unfit_tolerance(self.payload, self.tolerance_ms, timestamp_count)
+
+    @property
+    def signs_timestamp(self) -> bool:
+        return TIMESTAMP_PLACEHOLDER in self.payload
+
+
+def _refuse_unfit_tolerance(payload: str, tolerance_ms: int | None, timestamp_count: int) -> None:
+    if tolerance_ms is None:
+        if timestamp_count == 1:
+            raise SignatureToleranceInvalidError.missing(payload)
+
+        return
+
+    # A bool is an int in Python, and a float could be NaN: neither is a tolerance.
+    if isinstance(tolerance_ms, bool) or not isinstance(tolerance_ms, int) or tolerance_ms < 0:
+        raise SignatureToleranceInvalidError.not_whole_milliseconds(tolerance_ms)
+
+    if timestamp_count == 0:
+        raise SignatureToleranceInvalidError.without_timestamp(payload)

seampact_signed_webhooks-1.0.0/src/seampact/signed_webhooks/secret_lookup.py

@@ -0,0 +1,10 @@
+"""The secrets currently valid for a key id: one, or several during a rotation. The verifier never keeps them."""
+
+from collections.abc import Sequence
+from typing import Protocol
+
+
+class SecretLookup(Protocol):
+    def secrets_for(self, key_id: str) -> Sequence[str | bytes]:
+        """The secrets of the key id, text as UTF-8 or bytes; none when the key id is unknown."""
+        ...

seampact_signed_webhooks-1.0.0/src/seampact/signed_webhooks/signed_message.py

@@ -0,0 +1,29 @@
+"""What a template-signed request carries: the raw body and the signature header's timestamp and candidates.
+
+Its `repr` never shows the body or a signature, so a log line, a debugger or an error tracker that captures frame
+locals sees no sensitive byte.
+"""
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Final
+
+REDACTED: Final = "[redacted]"
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class SignedMessage:
+    """The decoded body bytes exactly as received, the signed timestamp text as received when the header carries one,
+    and every signature the header carries, still encoded."""
+
+    raw_body: bytes
+    timestamp: str | None
+    candidate_signatures: tuple[str, ...]
+
+    def __repr__(self) -> str:
+        return f"SignedMessage(raw_body={REDACTED}, timestamp={self.timestamp!r}, candidate_signatures={REDACTED})"
+
+    def __rich_repr__(self) -> Iterator[tuple[str, object]]:
+        yield "raw_body", REDACTED
+        yield "timestamp", self.timestamp
+        yield "candidate_signatures", REDACTED

seampact_signed_webhooks-1.0.0/src/seampact/signed_webhooks/verification.py

@@ -0,0 +1,32 @@
+"""The verifier's answer: verified, or the failure that refused the request."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Self
+
+
+class SignatureFailure(StrEnum):
+    """Why a signature failed; the authenticate hook answers its declared 401 for each of them."""
+
+    NO_SECRET = "no-secret"
+    TIMESTAMP_MISSING = "timestamp-missing"
+    TIMESTAMP_MALFORMED = "timestamp-malformed"
+    TIMESTAMP_OUTSIDE_TOLERANCE = "timestamp-outside-tolerance"
+    SIGNATURE_MISMATCH = "signature-mismatch"
+
+
+@dataclass(frozen=True, slots=True)
+class SignatureVerification:
+    failure: SignatureFailure | None
+
+    @classmethod
+    def passed(cls) -> Self:
+        return cls(None)
+
+    @classmethod
+    def failed(cls, failure: SignatureFailure) -> Self:
+        return cls(failure)
+
+    @property
+    def verified(self) -> bool:
+        return self.failure is None

seampact_signed_webhooks-1.0.0/src/seampact/signed_webhooks/verifier.py

@@ -0,0 +1,183 @@
+"""Verifies a template-signed request (ADR 0013 "Where the verification happens").
+
+Rebuilds the signed payload from the raw bytes, computes the MAC with each valid secret, compares it in constant time
+with each candidate, then checks the timestamp against the tolerance in both directions.
+"""
+
+import base64
+import contextlib
+import hashlib
+import hmac
+import re
+from collections.abc import Sequence
+from typing import Final
+
+from seampact.signed_webhooks.clock import Clock, SystemClock
+from seampact.signed_webhooks.placeholders import RAW_BODY_PLACEHOLDER, SUPPORTED_ALGORITHM, TIMESTAMP_PLACEHOLDER
+from seampact.signed_webhooks.refusals import EmptySignatureSecretError, UnsupportedSignatureAlgorithmError
+from seampact.signed_webhooks.scheme import SignatureEncoding, SignatureScheme
+from seampact.signed_webhooks.secret_lookup import SecretLookup
+from seampact.signed_webhooks.signed_message import REDACTED, SignedMessage
+from seampact.signed_webhooks.verification import SignatureFailure, SignatureVerification
+
+_HMAC_SHA256_BYTES: Final = 32
+_MILLISECONDS_PER_SECOND: Final = 1000
+# Longer than any Unix time in seconds for millions of years; beyond it the timestamp is outside every tolerance,
+# and `int()` of a very long text would raise.
+_MAX_TIMESTAMP_DIGITS: Final = 20
+_UNIX_SECONDS: Final = re.compile(r"[0-9]+")
+_HEX: Final = re.compile(r"(?:[0-9a-fA-F]{2})+")
+_BASE64: Final = re.compile(r"(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?")
+
+
+class _LookedUpSecrets:
+    """The secrets of one verification, held so that a frame capturing them shows no secret."""
+
+    __slots__ = ("_secrets",)
+
+    def __init__(self, secrets: Sequence[str | bytes]) -> None:
+        self._secrets = tuple(secrets)
+
+    def __repr__(self) -> str:
+        return REDACTED
+
+    def is_empty(self) -> bool:
+        return len(self._secrets) == 0
+
+    # Every secret is checked before any is kept or hashed, and no secret is ever bound to a local name: a frame
+    # captured at a refusal holds only this redacted holder and a position.
+    def usable(self, key_id: str) -> "_UsableSecrets":
+        for index in range(len(self._secrets)):
+            if not _is_usable_secret(self._secrets[index]):
+                raise EmptySignatureSecretError(key_id, index)
+
+        return _UsableSecrets(tuple(self._encoded(index, key_id) for index in range(len(self._secrets))))
+
+    # A text secret that is not valid Unicode (a byte that is not UTF-8 in an environment variable) is refused. The
+    # refusal is raised outside the handler, so it carries neither the encoding error nor the secret inside it.
+    def _encoded(self, index: int, key_id: str) -> bytes:
+        with contextlib.suppress(UnicodeEncodeError):
+            return _as_utf8(self._secrets[index])
+
+        raise EmptySignatureSecretError(key_id, index) from None
+
+
+class _UsableSecrets:
+    """The encoded secrets of one verification, kept in the holder through the MAC loop."""
+
+    __slots__ = ("_secrets",)
+
+    def __init__(self, secrets: tuple[bytes, ...]) -> None:
+        self._secrets = secrets
+
+    def __repr__(self) -> str:
+        return REDACTED
+
+    # Every secret against every candidate, without stopping at the first match.
+    def any_matches(self, payload: bytes, candidates: Sequence[bytes]) -> bool:
+        matched = False
+
+        for index in range(len(self._secrets)):
+            expected = hmac.new(self._secrets[index], payload, hashlib.sha256).digest()
+
+            for candidate in candidates:
+                if hmac.compare_digest(expected, candidate):
+                    matched = True
+
+        return matched
+
+
+def _as_utf8(secret: str | bytes) -> bytes:
+    return secret.encode("utf-8") if isinstance(secret, str) else secret
+
+
+def _is_usable_secret(secret: object) -> bool:
+    return isinstance(secret, str | bytes) and len(secret) > 0
+
+
+class TemplateSignatureVerifier:
+    """Verifies template-signed requests with the application's secrets; the clock is injectable for tests."""
+
+    __slots__ = ("_clock", "_secret_lookup")
+
+    def __init__(self, secret_lookup: SecretLookup, clock: Clock | None = None) -> None:
+        self._secret_lookup = secret_lookup
+        self._clock: Clock = SystemClock() if clock is None else clock
+
+    def verify(self, message: SignedMessage, key_id: str, scheme: SignatureScheme) -> SignatureVerification:
+        """Raises `UnsupportedSignatureAlgorithmError` for another algorithm than hmac-sha256, and
+        `EmptySignatureSecretError` when the lookup returns an empty secret, one that is neither text nor bytes, or
+        text that does not encode as UTF-8."""
+        if scheme.algorithm != SUPPORTED_ALGORITHM:
+            raise UnsupportedSignatureAlgorithmError(scheme.algorithm)
+
+        if scheme.signs_timestamp and message.timestamp is None:
+            return SignatureVerification.failed(SignatureFailure.TIMESTAMP_MISSING)
+
+        secrets = _LookedUpSecrets(self._secret_lookup.secrets_for(key_id))
+
+        if secrets.is_empty():
+            return SignatureVerification.failed(SignatureFailure.NO_SECRET)
+
+        usable_secrets = secrets.usable(key_id)
+
+        if not usable_secrets.any_matches(_signed_payload(message, scheme), _decoded_candidates(message, scheme)):
+            return SignatureVerification.failed(SignatureFailure.SIGNATURE_MISMATCH)
+
+        timestamp_failure = self._timestamp_failure(message.timestamp, scheme.tolerance_ms)
+
+        if timestamp_failure is not None:
+            return SignatureVerification.failed(timestamp_failure)
+
+        return SignatureVerification.passed()
+
+    def _timestamp_failure(self, timestamp: str | None, tolerance_ms: int | None) -> SignatureFailure | None:
+        if tolerance_ms is None:
+            return None
+
+        if timestamp is None:
+            return SignatureFailure.TIMESTAMP_MISSING
+
+        if _UNIX_SECONDS.fullmatch(timestamp) is None:
+            return SignatureFailure.TIMESTAMP_MALFORMED
+
+        if len(timestamp) > _MAX_TIMESTAMP_DIGITS:
+            return SignatureFailure.TIMESTAMP_OUTSIDE_TOLERANCE
+
+        signed_at_ms = int(timestamp) * _MILLISECONDS_PER_SECOND
+
+        if abs(self._clock.now_milliseconds() - signed_at_ms) > tolerance_ms:
+            return SignatureFailure.TIMESTAMP_OUTSIDE_TOLERANCE
+
+        return None
+
+
+# The payload with `{ts}` replaced by the timestamp text as received and `{rawBody}` by the raw bytes.
+def _signed_payload(message: SignedMessage, scheme: SignatureScheme) -> bytes:
+    before_body, after_body = scheme.payload.split(RAW_BODY_PLACEHOLDER, 1)
+    timestamp = message.timestamp or ""
+
+    return (
+        before_body.replace(TIMESTAMP_PLACEHOLDER, timestamp).encode("utf-8")
+        + message.raw_body
+        + after_body.replace(TIMESTAMP_PLACEHOLDER, timestamp).encode("utf-8")
+    )
+
+
+# A candidate that does not decode in the declared encoding, or decodes to the wrong length, never matches. The
+# patterns admit only text the decoders accept.
+def _decoded_candidate(candidate: str, encoding: SignatureEncoding) -> bytes | None:
+    if encoding is SignatureEncoding.HEX:
+        decoded = bytes.fromhex(candidate) if _HEX.fullmatch(candidate) else None
+    else:
+        decoded = base64.b64decode(candidate, validate=True) if _BASE64.fullmatch(candidate) else None
+
+    return decoded if decoded is not None and len(decoded) == _HMAC_SHA256_BYTES else None
+
+
+def _decoded_candidates(message: SignedMessage, scheme: SignatureScheme) -> list[bytes]:
+    return [
+        decoded
+        for decoded in (_decoded_candidate(candidate, scheme.encoding) for candidate in message.candidate_signatures)
+        if decoded is not None
+    ]