seampact-hooks 1.0.0__tar.gz

seampact_hooks-1.0.0/.gitignore

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

seampact_hooks-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_hooks-1.0.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.5
+Name: seampact-hooks
+Version: 1.0.0
+Summary: The seampact hook protocols and the values they exchange, for Python apps and generated code.
+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 hook protocols, the values they exchange and `Field` for Python apps, checked against the shared hooks shape.

seampact_hooks-1.0.0/README.md

@@ -0,0 +1 @@
+The hook protocols, the values they exchange and `Field` for Python apps, checked against the shared hooks shape.

seampact_hooks-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "seampact-hooks"
+version = "1.0.0"
+description = "The seampact hook protocols and the values they exchange, for Python apps and generated code."
+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_hooks-1.0.0/src/seampact/hooks/__init__.py

@@ -0,0 +1,71 @@
+"""The hook protocols an app implements and the values they exchange, with the shape every hooks package shares.
+
+A union's arms live in the union's module: `seampact.hooks.decision.Allowed`, `seampact.hooks.purpose.Field`.
+"""
+
+from seampact.hooks.authenticate_hook import AuthenticateHook
+from seampact.hooks.authenticate_request import AuthenticateRequest
+from seampact.hooks.authenticate_result import AuthenticateResult
+from seampact.hooks.decide_hook import DecideHook
+from seampact.hooks.decision import Decision
+from seampact.hooks.error_code_with_params import ErrorCodeWithParams
+from seampact.hooks.field import Absent, Field
+from seampact.hooks.field_direction import FieldDirection
+from seampact.hooks.idempotency_begin import IdempotencyBegin
+from seampact.hooks.idempotency_claim import IdempotencyClaim
+from seampact.hooks.idempotency_store import IdempotencyStore
+from seampact.hooks.operation_ref import OperationRef
+from seampact.hooks.purpose import Purpose
+from seampact.hooks.request_view import RequestView
+from seampact.hooks.requirement_kind import RequirementKind
+from seampact.hooks.requirement_request import RequirementRequest
+from seampact.hooks.resolve_scope_hook import ResolveScopeHook
+from seampact.hooks.resolve_scope_request import ResolveScopeRequest
+from seampact.hooks.resolved_scope import ResolvedScope
+from seampact.hooks.scope_id_source import ScopeIdSource
+from seampact.hooks.scope_resolution import ScopeResolution
+from seampact.hooks.signature_encoding import SignatureEncoding
+from seampact.hooks.signature_template import SignatureTemplate
+from seampact.hooks.signed_application_request import SignedApplicationRequest
+from seampact.hooks.signed_request import SignedRequest
+from seampact.hooks.signed_template_request import SignedTemplateRequest
+from seampact.hooks.stored_response import StoredResponse
+from seampact.hooks.subject_ref import SubjectRef
+from seampact.hooks.throttle_bucket import ThrottleBucket
+from seampact.hooks.unexpected_error_listener import UnexpectedErrorListener
+from seampact.hooks.unexpected_failure import UnexpectedFailure
+
+__all__ = [
+    "Absent",
+    "AuthenticateHook",
+    "AuthenticateRequest",
+    "AuthenticateResult",
+    "DecideHook",
+    "Decision",
+    "ErrorCodeWithParams",
+    "Field",
+    "FieldDirection",
+    "IdempotencyBegin",
+    "IdempotencyClaim",
+    "IdempotencyStore",
+    "OperationRef",
+    "Purpose",
+    "RequestView",
+    "RequirementKind",
+    "RequirementRequest",
+    "ResolveScopeHook",
+    "ResolveScopeRequest",
+    "ResolvedScope",
+    "ScopeIdSource",
+    "ScopeResolution",
+    "SignatureEncoding",
+    "SignatureTemplate",
+    "SignedApplicationRequest",
+    "SignedRequest",
+    "SignedTemplateRequest",
+    "StoredResponse",
+    "SubjectRef",
+    "ThrottleBucket",
+    "UnexpectedErrorListener",
+    "UnexpectedFailure",
+]

seampact_hooks-1.0.0/src/seampact/hooks/_redaction.py

@@ -0,0 +1,39 @@
+"""The redacted rendering of a value that may carry a secret, so a logged or captured object never leaks it."""
+
+import dataclasses
+from collections.abc import Iterator
+from typing import Any, ClassVar, Final
+
+REDACTED: Final = "[redacted]"
+
+
+class RedactedRepr:
+    """A base for the frozen dataclasses holding a credential or raw bytes: `repr`, `str`, `pprint` and `rich` print
+    `[redacted]` in place of each field named in `_REDACTED_FIELDS`. A subclass sets `repr=False` on its dataclass."""
+
+    __slots__ = ()
+
+    _REDACTED_FIELDS: ClassVar[frozenset[str]]
+    # Set by the subclass's dataclass decorator.
+    __dataclass_fields__: ClassVar[dict[str, dataclasses.Field[Any]]]
+
+    def _rendered_fields(self) -> Iterator[tuple[str, object]]:
+        for field in dataclasses.fields(self):
+            value = getattr(self, field.name)
+
+            yield field.name, _Redacted() if field.name in self._REDACTED_FIELDS else value
+
+    def __repr__(self) -> str:
+        rendered = ", ".join(f"{name}={value!r}" for name, value in self._rendered_fields())
+
+        return f"{type(self).__qualname__}({rendered})"
+
+    def __rich_repr__(self) -> Iterator[tuple[str, object]]:
+        yield from self._rendered_fields()
+
+
+class _Redacted:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return REDACTED

seampact_hooks-1.0.0/src/seampact/hooks/authenticate_hook.py

@@ -0,0 +1,11 @@
+"""The authenticate hook: a plain `def` or an `async def` method satisfies it."""
+
+from collections.abc import Awaitable
+from typing import Protocol
+
+from seampact.hooks.authenticate_request import AuthenticateRequest
+from seampact.hooks.authenticate_result import AuthenticateResult
+
+
+class AuthenticateHook(Protocol):
+    def authenticate(self, request: AuthenticateRequest, /) -> AuthenticateResult | Awaitable[AuthenticateResult]: ...

seampact_hooks-1.0.0/src/seampact/hooks/authenticate_request.py

@@ -0,0 +1,25 @@
+"""What the authenticate hook gets: the identity, its credentials and the request; credentials never show."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import ClassVar
+
+from seampact.hooks._redaction import RedactedRepr
+from seampact.hooks.operation_ref import OperationRef
+from seampact.hooks.request_view import RequestView
+from seampact.hooks.signed_request import SignedRequest
+
+
+@dataclass(frozen=True, slots=True, kw_only=True, repr=False)
+class AuthenticateRequest(RedactedRepr):
+    """`credentials` holds what the identity's schemes found in the request; `signature` is set for a signed one."""
+
+    _REDACTED_FIELDS: ClassVar[frozenset[str]] = frozenset({"credentials", "csrf_token"})
+
+    identity: str
+    credentials: object
+    csrf_token: str | None = None
+    signature: SignedRequest | None = None
+    request: RequestView
+    operation: OperationRef
+    extensions: Mapping[str, object]

seampact_hooks-1.0.0/src/seampact/hooks/authenticate_result.py

@@ -0,0 +1,18 @@
+"""The authenticate hook's answer: the authenticated principal, or a denial with its declared error."""
+
+from dataclasses import dataclass
+
+from seampact.hooks.error_code_with_params import ErrorCodeWithParams
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Authenticated:
+    principal: object
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Denied:
+    deny: ErrorCodeWithParams
+
+
+type AuthenticateResult = Authenticated | Denied

seampact_hooks-1.0.0/src/seampact/hooks/decide_hook.py

@@ -0,0 +1,11 @@
+"""The decide hook, which answers each right and rule: a plain `def` or an `async def` method satisfies it."""
+
+from collections.abc import Awaitable
+from typing import Protocol
+
+from seampact.hooks.decision import Decision
+from seampact.hooks.requirement_request import RequirementRequest
+
+
+class DecideHook(Protocol):
+    def decide(self, request: RequirementRequest, /) -> Decision | Awaitable[Decision]: ...

seampact_hooks-1.0.0/src/seampact/hooks/decision.py

@@ -0,0 +1,18 @@
+"""The decide hook's answer: allowed, or a denial with its declared error."""
+
+from dataclasses import dataclass
+
+from seampact.hooks.error_code_with_params import ErrorCodeWithParams
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Allowed:
+    pass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Denied:
+    deny: ErrorCodeWithParams
+
+
+type Decision = Allowed | Denied

seampact_hooks-1.0.0/src/seampact/hooks/error_code_with_params.py

@@ -0,0 +1,10 @@
+"""A declared error code and its parameters, the answer of a hook that denies."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ErrorCodeWithParams:
+    code: str
+    params: Mapping[str, object] | None = None

seampact_hooks-1.0.0/src/seampact/hooks/field.py

@@ -0,0 +1,13 @@
+"""`Field`: a value that may be absent, told apart from an explicit null (`None`) by the `Absent` sentinel."""
+
+from enum import Enum
+from typing import Literal
+
+
+class Absent(Enum):
+    """The one value of an absent field."""
+
+    ABSENT = "absent"
+
+
+type Field[T] = T | Literal[Absent.ABSENT]

seampact_hooks-1.0.0/src/seampact/hooks/field_direction.py

@@ -0,0 +1,8 @@
+"""Whether a field right is checked on the way in or on the way out."""
+
+from enum import StrEnum
+
+
+class FieldDirection(StrEnum):
+    INPUT = "input"
+    OUTPUT = "output"

seampact_hooks-1.0.0/src/seampact/hooks/idempotency_begin.py

@@ -0,0 +1,28 @@
+"""The idempotency store's answer to a claim: started, still running, a fingerprint mismatch, or a replay."""
+
+from dataclasses import dataclass
+
+from seampact.hooks.stored_response import StoredResponse
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Started:
+    pass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Running:
+    pass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Mismatch:
+    pass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Replay:
+    response: StoredResponse
+
+
+type IdempotencyBegin = Started | Running | Mismatch | Replay

seampact_hooks-1.0.0/src/seampact/hooks/idempotency_claim.py

@@ -0,0 +1,13 @@
+"""The claim an idempotent request makes on its key: the key, the request's fingerprint and the key's lifetime."""
+
+from dataclasses import dataclass
+
+from seampact.hooks.operation_ref import OperationRef
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class IdempotencyClaim:
+    key: str
+    fingerprint: str
+    lifetime_ms: int
+    operation: OperationRef

seampact_hooks-1.0.0/src/seampact/hooks/idempotency_store.py

@@ -0,0 +1,22 @@
+"""The store of idempotent requests: plain `def` or `async def` methods satisfy it."""
+
+from collections.abc import Awaitable
+from typing import Protocol
+
+from seampact.hooks.idempotency_begin import IdempotencyBegin
+from seampact.hooks.idempotency_claim import IdempotencyClaim
+from seampact.hooks.stored_response import StoredResponse
+
+
+class IdempotencyStore(Protocol):
+    def begin(self, claim: IdempotencyClaim, /) -> IdempotencyBegin | Awaitable[IdempotencyBegin]:
+        """Claims the key: started for a new key, or running, mismatch or replay for a known one."""
+        ...
+
+    def complete(self, key: str, response: StoredResponse, /) -> Awaitable[None] | None:
+        """Keeps the response for the key's replays."""
+        ...
+
+    def abandon(self, key: str, /) -> Awaitable[None] | None:
+        """Releases the key of a request that failed, so a retry starts again."""
+        ...

seampact_hooks-1.0.0/src/seampact/hooks/operation_ref.py

@@ -0,0 +1,9 @@
+"""The operation a hook call is about: its api and its operation id."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OperationRef:
+    api: str
+    id: str

seampact_hooks-1.0.0/src/seampact/hooks/purpose.py

@@ -0,0 +1,26 @@
+"""Why a requirement is checked: for the route, for one field, or for a sort key."""
+
+from dataclasses import dataclass
+
+from seampact.hooks.field_direction import FieldDirection
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Route:
+    pass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Field:
+    """`pointer` is the JSON pointer of the field in the body."""
+
+    pointer: str
+    direction: FieldDirection
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SortKey:
+    key: str
+
+
+type Purpose = Route | Field | SortKey

seampact_hooks-1.0.0/src/seampact/hooks/request_view.py

@@ -0,0 +1,19 @@
+"""What a hook sees of the HTTP request; its headers never show in a repr."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import ClassVar
+
+from seampact.hooks._redaction import RedactedRepr
+
+
+@dataclass(frozen=True, slots=True, kw_only=True, repr=False)
+class RequestView(RedactedRepr):
+    """`headers` holds every header by lower-case name, each with its values in order."""
+
+    _REDACTED_FIELDS: ClassVar[frozenset[str]] = frozenset({"headers"})
+
+    method: str
+    path: str
+    headers: Mapping[str, tuple[str, ...]]
+    client_address: str | None = None

seampact_hooks-1.0.0/src/seampact/hooks/requirement_kind.py

@@ -0,0 +1,8 @@
+"""Whether a requirement is a right or a rule."""
+
+from enum import StrEnum
+
+
+class RequirementKind(StrEnum):
+    RIGHT = "right"
+    RULE = "rule"

seampact_hooks-1.0.0/src/seampact/hooks/requirement_request.py

@@ -0,0 +1,43 @@
+"""What the decide hook gets: the requirement, the principal, the subject, the scopes and the request."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import ClassVar
+
+from seampact.hooks._redaction import RedactedRepr
+from seampact.hooks.operation_ref import OperationRef
+from seampact.hooks.purpose import Purpose
+from seampact.hooks.request_view import RequestView
+from seampact.hooks.requirement_kind import RequirementKind
+from seampact.hooks.resolved_scope import ResolvedScope
+from seampact.hooks.subject_ref import SubjectRef
+from seampact.hooks.throttle_bucket import ThrottleBucket
+
+
+@dataclass(frozen=True, slots=True, kw_only=True, repr=False)
+class RequirementRequest(RedactedRepr):
+    """`params` holds the use site's params as an instance of the right's or rule's generated params class, None when
+    it declares none; `scopes` are the resolved scopes, outermost first; `principal` is None for an anonymous request.
+    The rule proof is sensitive by construction, so it renders redacted."""
+
+    _REDACTED_FIELDS: ClassVar[frozenset[str]] = frozenset({"proof"})
+
+    @dataclass(frozen=True, slots=True, kw_only=True)
+    class Extensions:
+        """The extension values of the requirement and of the operation."""
+
+        requirement: Mapping[str, object]
+        operation: Mapping[str, object]
+
+    kind: RequirementKind
+    name: str
+    params: object | None = None
+    principal: object | None
+    subject: SubjectRef | None = None
+    scopes: tuple[ResolvedScope, ...]
+    proof: object | None = None
+    bucket: ThrottleBucket | None = None
+    purpose: Purpose
+    operation: OperationRef
+    request: RequestView
+    extensions: Extensions

seampact_hooks-1.0.0/src/seampact/hooks/resolve_scope_hook.py

@@ -0,0 +1,11 @@
+"""The resolve-scope hook: a plain `def` or an `async def` method satisfies it."""
+
+from collections.abc import Awaitable
+from typing import Protocol
+
+from seampact.hooks.resolve_scope_request import ResolveScopeRequest
+from seampact.hooks.scope_resolution import ScopeResolution
+
+
+class ResolveScopeHook(Protocol):
+    def resolve_scope(self, request: ResolveScopeRequest, /) -> ScopeResolution | Awaitable[ScopeResolution]: ...

seampact_hooks-1.0.0/src/seampact/hooks/resolve_scope_request.py

@@ -0,0 +1,25 @@
+"""What the resolve-scope hook gets: the scope, where its id comes from, the principal and the outer scopes."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from seampact.hooks.resolved_scope import ResolvedScope
+from seampact.hooks.scope_id_source import ScopeIdSource
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResolveScopeRequest:
+    """`outer_scopes` are the scopes already resolved, outermost first."""
+
+    @dataclass(frozen=True, slots=True, kw_only=True)
+    class Extensions:
+        """The extension values of the scope and of the operation."""
+
+        scope: Mapping[str, object]
+        operation: Mapping[str, object]
+
+    scope: str
+    source: ScopeIdSource
+    principal: object | None
+    outer_scopes: tuple[ResolvedScope, ...]
+    extensions: Extensions

seampact_hooks-1.0.0/src/seampact/hooks/resolved_scope.py

@@ -0,0 +1,10 @@
+"""A scope resolved for the request: its name, its id and, when loaded, its value."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResolvedScope:
+    scope: str
+    id: object
+    value: object | None = None

seampact_hooks-1.0.0/src/seampact/hooks/scope_id_source.py

@@ -0,0 +1,18 @@
+"""Where a scope's id comes from: declared in the contract, or resolved by the application from the request."""
+
+from dataclasses import dataclass
+
+from seampact.hooks.request_view import RequestView
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Declared:
+    id: object
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Custom:
+    request: RequestView
+
+
+type ScopeIdSource = Declared | Custom

seampact_hooks-1.0.0/src/seampact/hooks/scope_resolution.py

@@ -0,0 +1,19 @@
+"""The resolve-scope hook's answer: the resolved scope, or a denial with its declared error."""
+
+from dataclasses import dataclass
+
+from seampact.hooks.error_code_with_params import ErrorCodeWithParams
+from seampact.hooks.resolved_scope import ResolvedScope
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Resolved:
+    resolved: ResolvedScope
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Denied:
+    deny: ErrorCodeWithParams
+
+
+type ScopeResolution = Resolved | Denied

seampact_hooks-1.0.0/src/seampact/hooks/signature_encoding.py

@@ -0,0 +1,8 @@
+"""How a signature scheme writes its MAC in the header."""
+
+from enum import StrEnum
+
+
+class SignatureEncoding(StrEnum):
+    HEX = "hex"
+    BASE64 = "base64"

seampact_hooks-1.0.0/src/seampact/hooks/signature_template.py

@@ -0,0 +1,15 @@
+"""A template signature scheme of the IR (ADR 0013): algorithm, signed payload, encoding and tolerance."""
+
+from dataclasses import dataclass
+
+from seampact.hooks.signature_encoding import SignatureEncoding
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SignatureTemplate:
+    """`payload` holds the `{ts}` and `{rawBody}` placeholders; `tolerance_ms` is set when it holds `{ts}`."""
+
+    algorithm: str
+    payload: str
+    encoding: SignatureEncoding
+    tolerance_ms: int | None = None

seampact_hooks-1.0.0/src/seampact/hooks/signed_application_request.py

@@ -0,0 +1,19 @@
+"""A request signed by a scheme the application verifies itself; its body, signature and headers never show."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import ClassVar
+
+from seampact.hooks._redaction import RedactedRepr
+
+
+@dataclass(frozen=True, slots=True, kw_only=True, repr=False)
+class SignedApplicationRequest(RedactedRepr):
+    """The decoded body bytes exactly as received, the signature header, and the headers the scheme declares."""
+
+    _REDACTED_FIELDS: ClassVar[frozenset[str]] = frozenset({"raw_body", "signature_header", "headers"})
+
+    raw_body: bytes
+    signature_header: str
+    headers: Mapping[str, str]
+    key_id: str | None = None

seampact_hooks-1.0.0/src/seampact/hooks/signed_request.py

@@ -0,0 +1,6 @@
+"""A signed request: by a template scheme the verifier checks, or by one the application checks."""
+
+from seampact.hooks.signed_application_request import SignedApplicationRequest
+from seampact.hooks.signed_template_request import SignedTemplateRequest
+
+type SignedRequest = SignedTemplateRequest | SignedApplicationRequest

seampact_hooks-1.0.0/src/seampact/hooks/signed_template_request.py

@@ -0,0 +1,21 @@
+"""A request signed by a template scheme, for the verifier; its body and signatures never show in a repr."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from seampact.hooks._redaction import RedactedRepr
+from seampact.hooks.signature_template import SignatureTemplate
+
+
+@dataclass(frozen=True, slots=True, kw_only=True, repr=False)
+class SignedTemplateRequest(RedactedRepr):
+    """The decoded body bytes exactly as received, the signed timestamp text when the format has one, and every
+    signature the header carries, still encoded."""
+
+    _REDACTED_FIELDS: ClassVar[frozenset[str]] = frozenset({"raw_body", "candidate_signatures"})
+
+    raw_body: bytes
+    timestamp: str | None = None
+    candidate_signatures: tuple[str, ...]
+    key_id: str
+    template: SignatureTemplate

seampact_hooks-1.0.0/src/seampact/hooks/stored_response.py

@@ -0,0 +1,22 @@
+"""The response an idempotency store keeps for a replay; its body and header values never show in a repr."""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from seampact.hooks._redaction import RedactedRepr
+
+
+@dataclass(frozen=True, slots=True, kw_only=True, repr=False)
+class StoredResponse(RedactedRepr):
+    _REDACTED_FIELDS: ClassVar[frozenset[str]] = frozenset({"body"})
+
+    @dataclass(frozen=True, slots=True, kw_only=True, repr=False)
+    class Header(RedactedRepr):
+        _REDACTED_FIELDS: ClassVar[frozenset[str]] = frozenset({"value"})
+
+        name: str
+        value: str
+
+    status: int
+    headers: tuple[Header, ...]
+    body: bytes

seampact_hooks-1.0.0/src/seampact/hooks/subject_ref.py

@@ -0,0 +1,10 @@
+"""The subject a requirement is checked against: its type, its id and, when loaded, its record."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SubjectRef:
+    type: str
+    id: object
+    record: object | None = None

seampact_hooks-1.0.0/src/seampact/hooks/throttle_bucket.py

@@ -0,0 +1,14 @@
+"""The throttle bucket a requirement counts against."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ThrottleBucket:
+    """`key` is a fixed-size digest of the key values; `values` are the values of the key sources in order."""
+
+    id: str
+    key: str
+    values: tuple[object, ...]
+    limit: int | None = None
+    window_ms: int | None = None

seampact_hooks-1.0.0/src/seampact/hooks/unexpected_error_listener.py

@@ -0,0 +1,13 @@
+"""The listener the boundary calls for each failure it answers with the api's 500: a plain `def` or an `async def`
+satisfies it."""
+
+from collections.abc import Awaitable
+from typing import Protocol
+
+from seampact.hooks.unexpected_failure import UnexpectedFailure
+
+
+class UnexpectedErrorListener(Protocol):
+    def on_unexpected_error(self, failure: UnexpectedFailure, /) -> Awaitable[None] | None:
+        """Hears of the failure, to report it; the reply is the api's 500 whatever it does."""
+        ...

seampact_hooks-1.0.0/src/seampact/hooks/unexpected_failure.py

@@ -0,0 +1,12 @@
+"""One failure the boundary answered with the api's 500: the api, the operation when one matched, a reason that holds
+no input value, and the exception when one was raised."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UnexpectedFailure:
+    api: str
+    operation: str | None
+    reason: str
+    cause: BaseException | None = None