webagent-protocol 0.2.0__py3-none-any.whl

wap/spec/models.py

@@ -0,0 +1,453 @@
+"""Pydantic v2 data contracts for WebAgent Protocol (WAP/1.0).
+
+Every object that crosses the wire is defined here. The models are shared by
+the provider SDK (``wap.server``), the consumer SDK (``wap.client``) and the
+MCP bridge so that both sides of a conversation validate against exactly the
+same contract.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+import uuid
+from enum import StrEnum
+from typing import Any, Literal
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+WAP_VERSION = "1.0"
+WELL_KNOWN_PATH = "/.well-known/wap.json"
+# Also served (and tried by clients) for compatibility; other agent formats use this path too,
+# so clients must check that the document is a WAP manifest (it has ``wap_version``).
+LEGACY_WELL_KNOWN_PATH = "/.well-known/agent.json"
+WELL_KNOWN_PATHS = (WELL_KNOWN_PATH, LEGACY_WELL_KNOWN_PATH)
+INTERACT_PATH = "/wap/v1/interact"
+CHALLENGE_PATH = "/wap/v1/challenge"
+
+HEADER_VERSION = "X-WAP-Version"
+HEADER_SIGNATURE = "X-WAP-Signature"
+HEADER_KEY_ID = "X-WAP-Key-Id"
+HEADER_AGENT_KEY = "X-WAP-Agent-Key"
+
+POW_ALGORITHM = "sha256-leading-zero-hex"
+
+EFFECT_RANK: dict[str, int] = {"read": 0, "write": 1, "financial": 2}
+
+_HEX_RE = re.compile(r"^[0-9a-f]*$")
+_LABEL_RE = re.compile(r"^(?!-)[a-z0-9-]{1,63}(?<!-)$")
+_CAPABILITY_ID_RE = re.compile(r"^[a-z][a-z0-9_.-]{0,63}$")
+
+
+def _now() -> float:
+    return time.time()
+
+
+def _new_id() -> str:
+    return uuid.uuid4().hex
+
+
+def normalize_authority(value: str) -> str:
+    """Validate and normalise a WAP ``domain`` (an RFC 3986 authority without userinfo).
+
+    Accepts a fully-qualified domain name, ``localhost``, or an IPv4 literal,
+    optionally followed by ``:port``. The host part is lower-cased and a
+    trailing root dot is removed. Raises ``ValueError`` on anything else.
+    """
+    if not isinstance(value, str) or not value:
+        raise ValueError("domain must be a non-empty string")
+    raw = value.strip().lower()
+    if "://" in raw or "/" in raw or "@" in raw or "?" in raw or "#" in raw:
+        raise ValueError(f"domain must be a bare host[:port], got {value!r}")
+    host, sep, port = raw.rpartition(":") if raw.count(":") == 1 else (raw, "", "")
+    if sep:
+        if not port.isdigit() or not 0 < int(port) < 65536:
+            raise ValueError(f"invalid port in domain {value!r}")
+    host = host.rstrip(".")
+    if len(host) > 253 or not host:
+        raise ValueError(f"invalid host in domain {value!r}")
+    labels = host.split(".")
+    if not all(_LABEL_RE.match(label) for label in labels):
+        raise ValueError(f"domain {value!r} is not a valid hostname")
+    if all(label.isdigit() for label in labels):
+        if len(labels) != 4 or any(int(label) > 255 for label in labels):
+            raise ValueError(f"domain {value!r} is not a valid IPv4 literal")
+    elif len(labels) < 2 and host != "localhost":
+        raise ValueError(f"domain {value!r} must be fully qualified (or 'localhost')")
+    return f"{host}:{port}" if sep else host
+
+
+def authority_host(authority: str) -> str:
+    """Return the host component of a ``host[:port]`` authority."""
+    return authority.rsplit(":", 1)[0] if authority.count(":") == 1 else authority
+
+
+def is_local_authority(authority: str) -> bool:
+    """True for loopback authorities where plain HTTP is acceptable."""
+    host = authority_host(authority)
+    return host == "localhost" or host.endswith(".localhost") or host.startswith("127.")
+
+
+def _check_ijson(value: Any, path: str = "structured_data") -> None:
+    """I-JSON (RFC 7493): numbers must be exact IEEE-754 doubles so every language signs the same bytes."""
+    if isinstance(value, bool):
+        return
+    if isinstance(value, int):
+        if abs(value) > 2**53:
+            raise ValueError(f"{path}: integer {value} exceeds ±2**53; send it as a string")
+    elif isinstance(value, float):
+        if value != value or value in (float("inf"), float("-inf")):
+            raise ValueError(f"{path}: NaN and infinities are not allowed")
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            _check_ijson(item, f"{path}.{key}")
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            _check_ijson(item, f"{path}[{index}]")
+
+
+class Role(StrEnum):
+    USER_AGENT = "user_agent"
+    BUSINESS_AGENT = "business_agent"
+
+
+class ErrorCode(StrEnum):
+    """Machine-readable error codes (see docs/spec_rfc.md, Section 9)."""
+
+    INVALID_REQUEST = "invalid_request"
+    UNSUPPORTED_VERSION = "unsupported_version"
+    INVALID_SIGNATURE = "invalid_signature"
+    AUTH_REQUIRED = "auth_required"
+    FORBIDDEN = "forbidden"
+    SESSION_BUSY = "session_busy"
+    IDEMPOTENCY_CONFLICT = "idempotency_conflict"
+    EFFECTS_NOT_PERMITTED = "effects_not_permitted"
+    UNKNOWN_CAPABILITY = "unknown_capability"
+    REPLAY_DETECTED = "replay_detected"
+    VALIDATION_ERROR = "validation_error"
+    POW_REQUIRED = "pow_required"
+    POW_INVALID = "pow_invalid"
+    RATE_LIMITED = "rate_limited"
+    LOOP_DETECTED = "loop_detected"
+    CONVERSATION_LIMIT = "conversation_limit"
+    ACTION_FAILED = "action_failed"
+    INTERNAL_ERROR = "internal_error"
+
+
+ERROR_STATUS: dict[ErrorCode, int] = {
+    ErrorCode.INVALID_REQUEST: 400,
+    ErrorCode.UNSUPPORTED_VERSION: 400,
+    ErrorCode.INVALID_SIGNATURE: 401,
+    ErrorCode.AUTH_REQUIRED: 401,
+    ErrorCode.FORBIDDEN: 403,
+    ErrorCode.SESSION_BUSY: 409,
+    ErrorCode.IDEMPOTENCY_CONFLICT: 409,
+    ErrorCode.EFFECTS_NOT_PERMITTED: 403,
+    ErrorCode.POW_INVALID: 403,
+    ErrorCode.UNKNOWN_CAPABILITY: 404,
+    ErrorCode.REPLAY_DETECTED: 409,
+    ErrorCode.VALIDATION_ERROR: 422,
+    ErrorCode.POW_REQUIRED: 428,
+    ErrorCode.RATE_LIMITED: 429,
+    ErrorCode.LOOP_DETECTED: 409,
+    ErrorCode.CONVERSATION_LIMIT: 429,
+    ErrorCode.ACTION_FAILED: 502,
+    ErrorCode.INTERNAL_ERROR: 500,
+}
+
+
+class WAPModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+class Capability(WAPModel):
+    """A machine-executable action offered by a business agent."""
+
+    id: str = Field(description="Stable identifier, unique within a manifest.")
+    name: str = Field(min_length=1, max_length=128, description="Human readable name.")
+    description: str = Field(default="", max_length=4096)
+    input_schema: dict[str, Any] = Field(
+        default_factory=lambda: {"type": "object", "properties": {}},
+        description="JSON Schema (draft 2020-12) for the capability's structured_data input.",
+    )
+    output_schema: dict[str, Any] | None = Field(
+        default=None, description="JSON Schema describing structured_data in the reply."
+    )
+    requires_auth: bool = False
+    effects: Literal["read", "write", "financial"] = Field(
+        default="write",
+        description=(
+            "What calling the capability does: 'read' has no side effects; 'write' changes state at the "
+            "business (holds, bookings); 'financial' moves money or creates a payment obligation. "
+            "Clients use it to decide on confirmation, retries and idempotency keys."
+        ),
+    )
+    streaming: bool = Field(default=False, description="Whether the action streams tokens natively.")
+
+    @field_validator("id")
+    @classmethod
+    def _check_id(cls, value: str) -> str:
+        if not _CAPABILITY_ID_RE.match(value):
+            raise ValueError(
+                "capability id must match ^[a-z][a-z0-9_.-]{0,63}$ "
+                f"(lower-case, starting with a letter), got {value!r}"
+            )
+        return value
+
+    @field_validator("input_schema")
+    @classmethod
+    def _check_input_schema(cls, value: dict[str, Any]) -> dict[str, Any]:
+        if value.get("type", "object") != "object":
+            raise ValueError("input_schema must describe a JSON object")
+        return value
+
+
+def mcp_annotation_hints(capability: Capability) -> dict[str, bool]:
+    """MCP ``ToolAnnotations`` hints implied by a capability's ``effects``."""
+    return {
+        "read_only_hint": capability.effects == "read",
+        "destructive_hint": capability.effects == "financial",
+        "idempotent_hint": capability.effects == "read",
+        "open_world_hint": True,
+    }
+
+
+class RateLimitPolicy(WAPModel):
+    """Advisory rate limit published in the manifest and enforced by the server."""
+
+    requests_per_minute: int = Field(default=60, ge=1)
+    burst: int = Field(default=10, ge=1)
+    scopes: list[Literal["ip", "agent_key"]] = Field(default_factory=lambda: ["ip", "agent_key"])
+
+
+class AgentManifest(WAPModel):
+    """The document served at ``/.well-known/wap.json`` (RFC 8615)."""
+
+    wap_version: Literal["1.0"] = WAP_VERSION
+    domain: str = Field(description="Authority (host[:port]) the manifest is bound to.")
+    name: str = Field(min_length=1, max_length=256)
+    description: str = Field(default="", max_length=8192)
+    public_key: str = Field(description="Hex-encoded raw 32-byte Ed25519 public key.")
+    interaction_url: str
+    challenge_url: str | None = None
+    mcp_url: str | None = Field(
+        default=None, description="Optional MCP streamable-HTTP endpoint exposing the same capabilities as tools."
+    )
+    capabilities: list[Capability] = Field(default_factory=list)
+    pow_required: bool = False
+    pow_difficulty: int | None = Field(default=None, ge=1, le=16)
+    rate_limit_policy: dict[str, Any] = Field(default_factory=lambda: RateLimitPolicy().model_dump())
+    conversation_policy: dict[str, Any] | None = Field(
+        default=None, description="Loop-protection limits (max_turns, max_repeats, max_cycle_length, window_seconds)."
+    )
+    issued_at: float = Field(default_factory=_now)
+    expires_at: float | None = None
+    previous_keys: list[str] = Field(
+        default_factory=list, description="Hex keys this domain signed with before rotating to public_key."
+    )
+    key_endorsements: dict[str, str] = Field(
+        default_factory=dict,
+        description="previous key -> its signature over this manifest (excluding signature and key_endorsements).",
+    )
+    signature: str = Field(default="", description="Hex Ed25519 signature over the canonical manifest.")
+
+    @field_validator("domain")
+    @classmethod
+    def _check_domain(cls, value: str) -> str:
+        return normalize_authority(value)
+
+    @field_validator("public_key")
+    @classmethod
+    def _check_public_key(cls, value: str) -> str:
+        value = value.lower()
+        if len(value) != 64 or not _HEX_RE.match(value):
+            raise ValueError("public_key must be 64 hex characters (raw Ed25519 key)")
+        return value
+
+    @field_validator("signature")
+    @classmethod
+    def _check_signature(cls, value: str) -> str:
+        value = value.lower()
+        if value and (len(value) != 128 or not _HEX_RE.match(value)):
+            raise ValueError("signature must be 128 hex characters (raw Ed25519 signature)")
+        return value
+
+    @field_validator("interaction_url", "challenge_url", "mcp_url")
+    @classmethod
+    def _check_url(cls, value: str | None) -> str | None:
+        if value is None:
+            return value
+        parts = urlsplit(value)
+        if parts.scheme not in ("https", "http") or not parts.netloc:
+            raise ValueError(f"URL must be absolute http(s), got {value!r}")
+        return value
+
+    @model_validator(mode="after")
+    def _check_consistency(self) -> AgentManifest:
+        ids = [c.id for c in self.capabilities]
+        duplicates = {i for i in ids if ids.count(i) > 1}
+        if duplicates:
+            raise ValueError(f"duplicate capability ids: {sorted(duplicates)}")
+        if self.pow_required and self.pow_difficulty is None:
+            raise ValueError("pow_difficulty is required when pow_required is true")
+        if self.pow_required and self.challenge_url is None:
+            raise ValueError("challenge_url is required when pow_required is true")
+        for key in [*self.previous_keys, *self.key_endorsements]:
+            if len(key) != 64 or not _HEX_RE.match(key):
+                raise ValueError("previous_keys / key_endorsements must use 64-char lower-case hex keys")
+        if set(self.key_endorsements) - set(self.previous_keys):
+            raise ValueError("key_endorsements may only contain keys listed in previous_keys")
+        return self
+
+    def get_capability(self, capability_id: str) -> Capability | None:
+        for capability in self.capabilities:
+            if capability.id == capability_id:
+                return capability
+        return None
+
+    def is_expired(self, now: float | None = None) -> bool:
+        return self.expires_at is not None and (now or time.time()) >= self.expires_at
+
+
+class AgentMessage(WAPModel):
+    """A single signed turn in a WAP dialogue."""
+
+    wap_version: Literal["1.0"] = WAP_VERSION
+    message_id: str = Field(default_factory=_new_id, min_length=8, max_length=128)
+    session_id: str = Field(min_length=1, max_length=128)
+    role: Role
+    content: str = Field(default="", max_length=65536)
+    capability_id: str | None = None
+    structured_data: dict[str, Any] | None = None
+    in_reply_to: str | None = None
+    max_effects: Literal["read", "write", "financial"] | None = Field(
+        default=None,
+        description=(
+            "The strongest side effect the sender permits for this turn. A business agent must not run a "
+            "capability with stronger effects (e.g. an intent router booking something when only 'read' is "
+            "permitted) and instead answers effects_not_permitted naming the capability, so the user can confirm."
+        ),
+    )
+    idempotency_key: str | None = Field(
+        default=None,
+        min_length=8,
+        max_length=128,
+        description="Client-chosen key; a retry with the same key returns the original result instead of re-running.",
+    )
+    timestamp: float = Field(default_factory=_now)
+    pow_seed: str | None = None
+    pow_nonce: str | None = Field(default=None, max_length=128)
+    public_key: str | None = Field(
+        default=None, description="Signer's hex Ed25519 key. Required for user_agent messages."
+    )
+    signature: str = ""
+
+    @field_validator("public_key")
+    @classmethod
+    def _check_public_key(cls, value: str | None) -> str | None:
+        if value is None:
+            return value
+        value = value.lower()
+        if len(value) != 64 or not _HEX_RE.match(value):
+            raise ValueError("public_key must be 64 hex characters")
+        return value
+
+    @field_validator("signature")
+    @classmethod
+    def _check_signature(cls, value: str) -> str:
+        value = value.lower()
+        if value and (len(value) != 128 or not _HEX_RE.match(value)):
+            raise ValueError("signature must be 128 hex characters")
+        return value
+
+    @field_validator("structured_data")
+    @classmethod
+    def _check_interoperable_numbers(cls, value: dict[str, Any] | None) -> dict[str, Any] | None:
+        if value is not None:
+            _check_ijson(value)
+        return value
+
+    @model_validator(mode="after")
+    def _check_pow_pair(self) -> AgentMessage:
+        if (self.pow_seed is None) != (self.pow_nonce is None):
+            raise ValueError("pow_seed and pow_nonce must be supplied together")
+        return self
+
+
+class Challenge(WAPModel):
+    """A Hashcash-style proof-of-work challenge issued by ``/wap/v1/challenge``."""
+
+    algorithm: Literal["sha256-leading-zero-hex"] = POW_ALGORITHM
+    seed: str = Field(min_length=16, max_length=256)
+    difficulty: int = Field(ge=1, le=16)
+    issued_at: float = Field(default_factory=_now)
+    expires_at: float
+
+    @field_validator("seed")
+    @classmethod
+    def _check_seed(cls, value: str) -> str:
+        if not _HEX_RE.match(value):
+            raise ValueError("seed must be lower-case hex")
+        return value
+
+
+class ErrorDetail(WAPModel):
+    code: ErrorCode
+    message: str
+    retry_after: float | None = None
+    details: dict[str, Any] | None = None
+
+
+class ErrorResponse(WAPModel):
+    error: ErrorDetail
+
+    @classmethod
+    def build(
+        cls,
+        code: ErrorCode,
+        message: str,
+        *,
+        retry_after: float | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> ErrorResponse:
+        return cls(error=ErrorDetail(code=code, message=message, retry_after=retry_after, details=details))
+
+
+class StreamEventType(StrEnum):
+    META = "meta"
+    TOKEN = "token"
+    DATA = "data"
+    MESSAGE = "message"
+    ERROR = "error"
+
+
+__all__ = [
+    "WAP_VERSION",
+    "LEGACY_WELL_KNOWN_PATH",
+    "WELL_KNOWN_PATH",
+    "WELL_KNOWN_PATHS",
+    "INTERACT_PATH",
+    "CHALLENGE_PATH",
+    "HEADER_VERSION",
+    "HEADER_SIGNATURE",
+    "HEADER_KEY_ID",
+    "HEADER_AGENT_KEY",
+    "POW_ALGORITHM",
+    "EFFECT_RANK",
+    "ERROR_STATUS",
+    "AgentManifest",
+    "AgentMessage",
+    "Capability",
+    "Challenge",
+    "ErrorCode",
+    "ErrorDetail",
+    "ErrorResponse",
+    "RateLimitPolicy",
+    "Role",
+    "StreamEventType",
+    "authority_host",
+    "is_local_authority",
+    "mcp_annotation_hints",
+    "normalize_authority",
+]

wap/spec/pow.py

@@ -0,0 +1,230 @@
+"""Hashcash-style proof-of-work used to defend business agents against token draining.
+
+A challenge is ``{"seed": "<hex>", "difficulty": N}``. A client solves it by
+finding a ``nonce`` such that ``SHA256(seed + nonce)`` (UTF-8 concatenation,
+hex digest) starts with ``N`` ``"0"`` characters. The expected work is
+``16**N`` hash evaluations for the client and exactly one for the server.
+
+Challenges are *stateless* to issue: the seed embeds a random salt, its expiry
+time and an HMAC tag computed with a server secret, so the server does not need
+to remember what it handed out. It only remembers *spent* seeds (until they
+expire) so a solution cannot be replayed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import hmac
+import itertools
+import os
+import secrets
+import struct
+import threading
+import time
+from dataclasses import dataclass
+
+from .models import Challenge
+
+_SALT_BYTES = 16
+_EXPIRY_BYTES = 8
+_TAG_BYTES = 16
+SEED_HEX_LENGTH = 2 * (_SALT_BYTES + _EXPIRY_BYTES + _TAG_BYTES)
+MAX_NONCE_LENGTH = 128
+
+
+class PowError(Exception):
+    """Base class for proof-of-work verification failures."""
+
+    reason = "invalid"
+
+
+class PowMalformed(PowError):
+    reason = "malformed"
+
+
+class PowForged(PowError):
+    reason = "forged"
+
+
+class PowExpired(PowError):
+    reason = "expired"
+
+
+class PowReplayed(PowError):
+    reason = "replayed"
+
+
+class PowInsufficient(PowError):
+    reason = "insufficient_work"
+
+
+def pow_digest(seed: str, nonce: str) -> str:
+    return hashlib.sha256((seed + nonce).encode("utf-8")).hexdigest()
+
+
+def check_solution(seed: str, nonce: str, difficulty: int) -> bool:
+    """Return ``True`` iff ``nonce`` solves ``seed`` at ``difficulty``."""
+    if not nonce or len(nonce) > MAX_NONCE_LENGTH:
+        return False
+    return pow_digest(seed, nonce).startswith("0" * difficulty)
+
+
+def solve(seed: str, difficulty: int, *, start: int = 0, max_iterations: int | None = None) -> str:
+    """Find a nonce for ``seed`` by brute force. CPU bound; see :func:`solve_async`."""
+    if difficulty < 1:
+        raise ValueError("difficulty must be >= 1")
+    target = "0" * difficulty
+    prefix = hashlib.sha256(seed.encode("utf-8"))
+    counter = itertools.count(start) if max_iterations is None else range(start, start + max_iterations)
+    for i in counter:
+        nonce = format(i, "x")
+        h = prefix.copy()
+        h.update(nonce.encode("ascii"))
+        if h.hexdigest().startswith(target):
+            return nonce
+    raise RuntimeError(f"no solution found within {max_iterations} iterations")
+
+
+async def solve_async(seed: str, difficulty: int) -> str:
+    """Solve a challenge in a worker thread so the event loop stays responsive."""
+    return await asyncio.to_thread(solve, seed, difficulty)
+
+
+def solve_challenge(challenge: Challenge) -> str:
+    return solve(challenge.seed, challenge.difficulty)
+
+
+@dataclass(frozen=True)
+class PowVerification:
+    seed: str
+    nonce: str
+    difficulty: int
+    expires_at: float
+
+
+class PowEngine:
+    """Issues and verifies stateless, single-use proof-of-work challenges."""
+
+    def __init__(
+        self,
+        difficulty: int = 4,
+        ttl_seconds: float = 120.0,
+        secret: bytes | None = None,
+        max_spent: int = 100_000,
+    ) -> None:
+        if not 1 <= difficulty <= 16:
+            raise ValueError("difficulty must be between 1 and 16")
+        if ttl_seconds <= 0:
+            raise ValueError("ttl_seconds must be positive")
+        self.difficulty = difficulty
+        self.ttl_seconds = ttl_seconds
+        self._secret = secret or os.urandom(32)
+        self._spent: dict[str, float] = {}
+        self._max_spent = max_spent
+        self._lock = threading.Lock()
+
+    def _tag(self, salt: bytes, expiry: bytes, difficulty: int) -> bytes:
+        mac = hmac.new(self._secret, salt + expiry + bytes([difficulty]), hashlib.sha256)
+        return mac.digest()[:_TAG_BYTES]
+
+    def issue(self, difficulty: int | None = None, now: float | None = None) -> Challenge:
+        """Mint a new challenge. The difficulty is authenticated by the seed's HMAC."""
+        difficulty = self.difficulty if difficulty is None else difficulty
+        if not 1 <= difficulty <= 16:
+            raise ValueError("difficulty must be between 1 and 16")
+        now = time.time() if now is None else now
+        expires_at = now + self.ttl_seconds
+        salt = secrets.token_bytes(_SALT_BYTES)
+        expiry = struct.pack(">d", expires_at)
+        seed = (salt + expiry + self._tag(salt, expiry, difficulty)).hex()
+        return Challenge(seed=seed, difficulty=difficulty, issued_at=now, expires_at=expires_at)
+
+    def _decode(self, seed: str) -> tuple[bytes, bytes, bytes, float]:
+        if len(seed) != SEED_HEX_LENGTH:
+            raise PowMalformed("seed has the wrong length")
+        try:
+            raw = bytes.fromhex(seed)
+        except ValueError as exc:
+            raise PowMalformed("seed is not hex") from exc
+        salt = raw[:_SALT_BYTES]
+        expiry = raw[_SALT_BYTES : _SALT_BYTES + _EXPIRY_BYTES]
+        tag = raw[_SALT_BYTES + _EXPIRY_BYTES :]
+        (expires_at,) = struct.unpack(">d", expiry)
+        return salt, expiry, tag, expires_at
+
+    def _authenticate(self, seed: str) -> tuple[int, float]:
+        """Recover the difficulty bound into ``seed`` and its expiry, or raise."""
+        salt, expiry, tag, expires_at = self._decode(seed)
+        for difficulty in range(1, 17):
+            if hmac.compare_digest(tag, self._tag(salt, expiry, difficulty)):
+                return difficulty, expires_at
+        raise PowForged("seed was not issued by this server")
+
+    def _prune(self, now: float) -> None:
+        expired = [s for s, exp in self._spent.items() if exp <= now]
+        for s in expired:
+            del self._spent[s]
+
+    def check(
+        self, seed: str, nonce: str, now: float | None = None, *, min_difficulty: int | None = None
+    ) -> PowVerification:
+        """Verify authenticity, expiry and work *without* tracking reuse (see :meth:`verify`).
+
+        Servers with several workers call this and then record the seed as spent in a
+        shared store. Raises a :class:`PowError` subclass on failure.
+        """
+        now = time.time() if now is None else now
+        if not isinstance(nonce, str) or not nonce or len(nonce) > MAX_NONCE_LENGTH:
+            raise PowMalformed("nonce is missing or too long")
+        difficulty, expires_at = self._authenticate(seed)
+        if expires_at <= now:
+            raise PowExpired("challenge has expired")
+        if min_difficulty is not None and difficulty < min_difficulty:
+            raise PowInsufficient(f"challenge difficulty {difficulty} is below the required {min_difficulty}")
+        if not check_solution(seed, nonce, difficulty):
+            raise PowInsufficient(f"hash does not have {difficulty} leading zeros")
+        return PowVerification(seed=seed, nonce=nonce, difficulty=difficulty, expires_at=expires_at)
+
+    def verify(self, seed: str, nonce: str, now: float | None = None, *, consume: bool = True) -> PowVerification:
+        """Verify a solution and (by default) mark the seed as spent in this process.
+
+        Raises a :class:`PowError` subclass describing why verification failed.
+        """
+        now = time.time() if now is None else now
+        result = self.check(seed, nonce, now)
+        expires_at = result.expires_at
+        with self._lock:
+            if seed in self._spent:
+                raise PowReplayed("challenge has already been used")
+            if consume:
+                if len(self._spent) >= self._max_spent:
+                    self._prune(now)
+                if len(self._spent) >= self._max_spent:
+                    raise PowReplayed("too many outstanding solutions; retry shortly")
+                self._spent[seed] = expires_at
+        return result
+
+    def spent_count(self) -> int:
+        with self._lock:
+            self._prune(time.time())
+            return len(self._spent)
+
+
+__all__ = [
+    "MAX_NONCE_LENGTH",
+    "PowEngine",
+    "PowError",
+    "PowExpired",
+    "PowForged",
+    "PowInsufficient",
+    "PowMalformed",
+    "PowReplayed",
+    "PowVerification",
+    "SEED_HEX_LENGTH",
+    "check_solution",
+    "pow_digest",
+    "solve",
+    "solve_async",
+    "solve_challenge",
+]