mishmar 0.2.0__py3-none-any.whl

mishmar/__init__.py

@@ -0,0 +1,27 @@
+"""The Mishmar client: sign and submit proposals, read decisions, answer the signer channel."""
+
+from .agentkey import AgentKey, request_signing_bytes, verify, verify_request
+from .canon import canonical_json
+from .client import DEFAULT_RETRIES, Client, EngineError, Retries
+from .proposal import Proposal, VenueMessage, is_decimal, new_nonce, rfc3339
+from .signer import Signer, download_binary, find_binary
+
+__all__ = [
+    "DEFAULT_RETRIES",
+    "AgentKey",
+    "Client",
+    "EngineError",
+    "Proposal",
+    "Retries",
+    "Signer",
+    "VenueMessage",
+    "canonical_json",
+    "download_binary",
+    "find_binary",
+    "is_decimal",
+    "new_nonce",
+    "request_signing_bytes",
+    "rfc3339",
+    "verify",
+    "verify_request",
+]

mishmar/_time.py

@@ -0,0 +1,31 @@
+"""Times as the contract writes them."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+
+def rfc3339(dt: datetime) -> str:
+    """Format a time as the contract wants it: UTC, Z suffix, fraction trimmed."""
+    if dt.tzinfo is None:
+        raise ValueError("times must be timezone-aware")
+    dt = dt.astimezone(UTC)
+    text = dt.strftime("%Y-%m-%dT%H:%M:%S")
+    if dt.microsecond:
+        text += "." + f"{dt.microsecond:06d}".rstrip("0")
+    return text + "Z"
+
+
+def parse_time(value: Any) -> datetime:
+    """A timezone-aware datetime from a datetime or an RFC 3339 string."""
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            raise ValueError("times must be timezone-aware")
+        return value
+    if isinstance(value, str):
+        dt = datetime.fromisoformat(value)
+        if dt.tzinfo is None:
+            raise ValueError(f"time {value!r} has no offset")
+        return dt
+    raise TypeError(f"not a time: {value!r}")

mishmar/agentkey.py

@@ -0,0 +1,188 @@
+"""The agent's identity: an Ed25519 key whose public half the engine stores.
+
+The engine shows the secret once, as ``msk_<prefix>_<seed>``: a label, then
+the 32-byte seed in base64url without padding. The key id (``key_…``) is
+separate and public.
+
+The key signs two things: proposals (see proposal.py) and, under the
+contract's agentAuth scheme, every other agent-facing request: four headers
+carry the key id, the time, a nonce and an Ed25519 signature over the canonical
+JSON of ``{bodySha256, keyId, method, nonce, path, query, signedAt}``. The bytes
+are pinned in spec/vectors/agent-request-signing.json.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+from datetime import UTC, datetime
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+from ._time import rfc3339
+from .canon import canonical_json
+
+SEED_SIZE = 32
+
+HEADER_KEY_ID = "X-Mishmar-Key-Id"
+HEADER_SIGNED_AT = "X-Mishmar-Signed-At"
+HEADER_NONCE = "X-Mishmar-Nonce"
+HEADER_SIGNATURE = "X-Mishmar-Signature"
+
+
+def _b64url_decode(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def new_nonce() -> str:
+    """A fresh nonce: 16 random bytes, hex."""
+    return secrets.token_hex(16)
+
+
+def request_signing_bytes(
+    *,
+    key_id: str,
+    method: str,
+    path: str,
+    query: str = "",
+    body: bytes = b"",
+    nonce: str,
+    signed_at: str,
+) -> bytes:
+    """What the agent signs for a request. ``path`` is without the server
+    prefix (``/agent/decisions``), ``query`` the raw query string without the
+    ``?``, ``signed_at`` exactly as the header carries it."""
+    fields: dict[str, str] = {
+        "keyId": key_id,
+        "method": method.upper(),
+        "nonce": nonce,
+        "path": path,
+        "signedAt": signed_at,
+    }
+    if query:
+        fields["query"] = query
+    if body:
+        fields["bodySha256"] = hashlib.sha256(body).hexdigest()
+    return canonical_json(fields)
+
+
+class AgentKey:
+    """The agent's private key."""
+
+    def __init__(self, private: Ed25519PrivateKey):
+        self._private = private
+
+    @classmethod
+    def parse(cls, secret: str) -> AgentKey:
+        """Read the secret the engine showed when the key was issued."""
+        # msk_<prefix>_<seed>: the seed is base64url and may itself contain
+        # '_', so split on the first two underscores only.
+        parts = secret.strip().split("_", 2)
+        if len(parts) != 3 or parts[0] != "msk":
+            raise ValueError("malformed agent secret: expected msk_<prefix>_<seed>")
+        try:
+            seed = _b64url_decode(parts[2])
+        except ValueError as err:
+            raise ValueError(
+                "malformed agent secret: the seed is not base64url"
+            ) from err
+        if len(seed) != SEED_SIZE:
+            raise ValueError("malformed agent secret: the seed is not 32 bytes")
+        return cls.from_seed(seed)
+
+    @classmethod
+    def from_seed(cls, seed: bytes) -> AgentKey:
+        return cls(Ed25519PrivateKey.from_private_bytes(seed))
+
+    def sign(self, message: bytes) -> str:
+        """The base64 (standard, padded) Ed25519 signature of message."""
+        return base64.b64encode(self._private.sign(message)).decode("ascii")
+
+    def sign_request(
+        self,
+        key_id: str,
+        method: str,
+        path: str,
+        *,
+        query: str = "",
+        body: bytes = b"",
+        nonce: str | None = None,
+        signed_at: datetime | None = None,
+    ) -> dict[str, str]:
+        """The four agentAuth headers for a request; a nonce and the time are
+        made here when not given."""
+        nonce = nonce or new_nonce()
+        signed_at_text = rfc3339(signed_at or datetime.now(UTC))
+        message = request_signing_bytes(
+            key_id=key_id,
+            method=method,
+            path=path,
+            query=query,
+            body=body,
+            nonce=nonce,
+            signed_at=signed_at_text,
+        )
+        return {
+            HEADER_KEY_ID: key_id,
+            HEADER_SIGNED_AT: signed_at_text,
+            HEADER_NONCE: nonce,
+            HEADER_SIGNATURE: self.sign(message),
+        }
+
+    @property
+    def public_key(self) -> bytes:
+        return self._private.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+
+    @property
+    def public_key_b64(self) -> str:
+        """The public half as the API stores and returns it."""
+        return base64.b64encode(self.public_key).decode("ascii")
+
+
+def secret(prefix: str, seed: bytes) -> str:
+    """Render a seed the way the engine shows it."""
+    return prefix + "_" + base64.urlsafe_b64encode(seed).rstrip(b"=").decode("ascii")
+
+
+def verify(public_key_b64: str, message: bytes, signature_b64: str) -> bool:
+    """Check a base64 signature over message with a public key in the API's form."""
+    try:
+        public = Ed25519PublicKey.from_public_bytes(
+            base64.b64decode(public_key_b64, validate=True)
+        )
+        public.verify(base64.b64decode(signature_b64, validate=True), message)
+        return True
+    except (ValueError, InvalidSignature):
+        return False
+
+
+def verify_request(
+    public_key_b64: str,
+    *,
+    key_id: str,
+    method: str,
+    path: str,
+    query: str,
+    body: bytes,
+    nonce: str,
+    signed_at: str,
+    signature_b64: str,
+) -> bool:
+    """The engine's side of agentAuth: check the headers against the request.
+    Freshness and nonce replay are the caller's checks."""
+    message = request_signing_bytes(
+        key_id=key_id,
+        method=method,
+        path=path,
+        query=query,
+        body=body,
+        nonce=nonce,
+        signed_at=signed_at,
+    )
+    return verify(public_key_b64, message, signature_b64)

mishmar/canon.py

@@ -0,0 +1,46 @@
+"""Canonical JSON: the bytes an agent signs and the engine verifies.
+
+The rules match Go's encoding/json, which the engine uses (see canon/ in the
+repo root and spec/vectors): one object, keys sorted, no whitespace, keys
+whose value is None left out at every depth, strings with Go's escapes.
+Python's json module agrees on everything but the HTML-safe escapes, which
+are added here. Numbers never appear in what Mishmar signs, so they are
+refused rather than formatted differently from Go.
+"""
+
+import json
+from typing import Any
+
+# What Go escapes beyond the JSON minimum: HTML-significant characters and
+# the two line separators. Python with ensure_ascii=False writes them raw.
+_GO_ESCAPES = {
+    "<": "\\u003c",
+    ">": "\\u003e",
+    "&": "\\u0026",
+    "
": "\\u2028",
+    "
": "\\u2029",
+}
+
+
+def _strip(value: Any) -> Any:
+    if isinstance(value, bool) or value is None or isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        return {k: _strip(v) for k, v in value.items() if v is not None}
+    if isinstance(value, (list, tuple)):
+        return [_strip(v) for v in value]
+    if isinstance(value, (int, float)):
+        raise TypeError(
+            f"canonical_json: numbers are not signed by Mishmar; send {value!r} as a decimal string"
+        )
+    raise TypeError(f"canonical_json: cannot encode {type(value).__name__}")
+
+
+def canonical_json(value: Any) -> bytes:
+    """Return the canonical UTF-8 encoding of value."""
+    text = json.dumps(
+        _strip(value), sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    )
+    for raw, escaped in _GO_ESCAPES.items():
+        text = text.replace(raw, escaped)
+    return text.encode("utf-8")

mishmar/client.py

@@ -0,0 +1,328 @@
+"""A small HTTP client for the engine, on the standard library only.
+
+Proposals go to POST /proposals with the signature in the body. Everything
+else an agent may call (its own decisions, approvals, positions, PnL, trading accounts,
+and the signer channel) is under /agent and signed with the agentAuth
+headers, so a bot can function without an operator token and cannot act on
+the account.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+from .agentkey import AgentKey
+from .proposal import Proposal
+
+RESOLVED_APPROVAL = ("approved", "rejected", "expired")
+
+#: The answers that mean the request did nothing and may go again: 503 while
+#: the engine restarts, 429 when this caller sent too many.
+RETRYABLE = (503, 429)
+
+
+class EngineError(Exception):
+    """The engine answered with an error: ``status`` (HTTP), ``code`` and ``message`` from its body."""
+
+    def __init__(self, status: int, code: str, message: str):
+        super().__init__(f"{status} {code}: {message}")
+        self.status, self.code, self.message = status, code, message
+        #: The ``Retry-After`` header of a 429, when the engine sent one.
+        self.retry_after: str | None = None
+
+
+@dataclass(frozen=True)
+class Retries:
+    """How a call the engine did nothing with goes again: 503 ``unavailable``
+    while the engine restarts (its drain is 28 s) and 429 ``rate_limited``.
+    The same request is sent again after the seconds in ``Retry-After`` when
+    the engine names them, otherwise after a wait that doubles from
+    ``min_wait`` to ``max_wait`` with jitter, until ``budget`` seconds have
+    passed since the first attempt; then the last answer is raised. Nothing
+    else is retried: a 413 ``too_large`` would come back the same, and any
+    other answer means the request was taken. The defaults cover a restart.
+    """
+
+    budget: float = 45.0
+    min_wait: float = 0.25
+    max_wait: float = 8.0
+
+    def wait(
+        self, attempt: int, status: int, retry_after: str | None, elapsed: float
+    ) -> float | None:
+        """Seconds to wait before attempt ``attempt + 1`` (from 0), or ``None``
+        to stop and raise the answer."""
+        if status not in RETRYABLE:
+            return None
+        wait = _parse_retry_after(retry_after)
+        if wait is None:
+            step = min(self.min_wait * (2 ** min(attempt, 20)), self.max_wait)
+            wait = step / 2 + random.uniform(0, step / 2)
+        if elapsed + wait > self.budget:
+            return None
+        return wait
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        secs = int(value)
+        return float(secs) if secs >= 0 else None
+    except ValueError:
+        pass
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    return max(when.timestamp() - time.time(), 0.0)
+
+
+#: The default policy; see :class:`Retries`.
+DEFAULT_RETRIES = Retries()
+
+
+class Client:
+    """Talks to one engine as one agent. The trading key's share lives in the
+    agent's signer, never here: this client proposes, reads, and relays the
+    signer channel.
+
+    ``retries`` is how a call the engine did nothing with goes again
+    (:class:`Retries`, on by default); ``None`` turns retries off."""
+
+    def __init__(
+        self,
+        engine_url: str,
+        agent_key: AgentKey,
+        key_id: str,
+        *,
+        timeout: float = 10.0,
+        retries: Retries | None = DEFAULT_RETRIES,
+    ):
+        self.engine_url = engine_url.rstrip("/")
+        self.agent_key = agent_key
+        self.key_id = key_id
+        self.timeout = timeout
+        self.retries = retries
+        self._sleep: Callable[[float], None] = time.sleep
+
+    # Proposals
+
+    def propose(self, proposal: Proposal) -> dict[str, Any]:
+        """Sign the proposal with the agent's key (unless already signed) and
+        submit it. Returns the decision as the engine recorded it."""
+        if not proposal.key_id:
+            proposal.key_id = self.key_id
+        if proposal.signature is None:
+            proposal.sign(self.agent_key)
+        return self._call("POST", "/proposals", body=proposal.to_wire())
+
+    # Reads, scoped to this agent
+
+    def decisions(
+        self,
+        *,
+        trading_account_id: str | None = None,
+        verdict: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> dict[str, Any]:
+        """A page of this agent's decisions, newest first."""
+        params = {
+            "tradingAccountId": trading_account_id,
+            "verdict": verdict,
+            "from": since,
+            "to": until,
+            "cursor": cursor,
+            "limit": limit,
+        }
+        return self._agent_call("GET", "/agent/decisions", query=params)
+
+    def decision(self, decision_id: str) -> dict[str, Any]:
+        return self._agent_call(
+            "GET", f"/agent/decisions/{urllib.parse.quote(decision_id, safe='')}"
+        )
+
+    def approvals(self, status: str | None = None) -> list[dict[str, Any]]:
+        return self._agent_call("GET", "/agent/approvals", query={"status": status})
+
+    def positions(self) -> list[dict[str, Any]]:
+        return self._agent_call("GET", "/agent/positions")
+
+    def pnl(self, start: str | None = None, end: str | None = None) -> dict[str, Any]:
+        """Daily PnL of this agent; ``start`` and ``end`` are dates (YYYY-MM-DD)."""
+        return self._agent_call("GET", "/agent/pnl", query={"from": start, "to": end})
+
+    def trading_account(self, trading_account_id: str) -> dict[str, Any]:
+        """A trading account as this agent may see it, its setup without any secret."""
+        return self._agent_call(
+            "GET",
+            f"/agent/trading-accounts/{urllib.parse.quote(trading_account_id, safe='')}",
+        )
+
+    def venue_rules(
+        self, trading_account_id: str, symbol: str | None = None
+    ) -> dict[str, Any]:
+        """What the trading account's venue accepts per symbol (tick, step,
+        minimums), as the engine last read it; ``symbol`` narrows it to one."""
+        return self._agent_call(
+            "GET",
+            f"/agent/trading-accounts/{urllib.parse.quote(trading_account_id, safe='')}/venue-rules",
+            query={"symbol": symbol},
+        )
+
+    def wait(
+        self, decision_id: str, timeout: float = 60.0, interval: float = 1.0
+    ) -> dict[str, Any]:
+        """Poll a decision until it is no longer waiting for a person, or
+        until timeout; returns the last decision read either way."""
+        deadline = time.monotonic() + timeout
+        while True:
+            d = self.decision(decision_id)
+            if resolved(d) or time.monotonic() >= deadline:
+                return d
+            time.sleep(min(interval, max(0.0, deadline - time.monotonic())))
+
+    # The signer channel
+
+    def signer_poll(self, wait_seconds: int = 25) -> list[dict[str, Any]]:
+        """Wait up to wait_seconds for requests this agent's signer must sign."""
+        return self._agent_call(
+            "POST",
+            "/agent/signer/poll",
+            body={"waitSeconds": wait_seconds},
+            timeout=self.timeout + wait_seconds,
+        )
+
+    def signer_commitments(
+        self, venue_key_id: str, count: int | None = None
+    ) -> dict[str, Any]:
+        """Take up to ``count`` of the engine's single-use FROST commitments for
+        one-shot signing with a venue key (CommitmentBatch); by default as many
+        as the account allows."""
+        body: dict[str, Any] = {"venueKeyId": venue_key_id}
+        if count is not None:
+            body["count"] = count
+        return self._agent_call("POST", "/agent/signer/commitments", body=body)
+
+    def signer_answer(self, request_id: str, answer: dict[str, Any]) -> None:
+        """Answer a sign request: a share, a signature, a venue response or a refusal (SignerAnswer)."""
+        self._agent_call(
+            "POST",
+            f"/agent/signer/requests/{urllib.parse.quote(request_id, safe='')}/answer",
+            body=answer,
+        )
+
+    # Plumbing
+
+    def _agent_call(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, Any] | None = None,
+        body: Any = None,
+        timeout: float | None = None,
+    ) -> Any:
+        params = {k: v for k, v in (query or {}).items() if v is not None}
+        query_text = urllib.parse.urlencode(params)
+        data = b"" if body is None else json.dumps(body).encode("utf-8")
+
+        # Each attempt is signed anew, with its own nonce and time, so a
+        # retry is never a replay.
+        def sign() -> dict[str, str]:
+            return self.agent_key.sign_request(
+                self.key_id, method, path, query=query_text, body=data
+            )
+
+        return self._call(
+            method,
+            path + ("?" + query_text if query_text else ""),
+            body=body,
+            sign=sign,
+            timeout=timeout,
+        )
+
+    def _call(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        sign: Callable[[], dict[str, str]] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        """Send the request, again after an answer that did nothing (``retries``),
+        and return the final answer decoded; ``sign`` makes each attempt's headers."""
+        data = None if body is None else json.dumps(body).encode("utf-8")
+        start = time.monotonic()
+        attempt = 0
+        while True:
+            try:
+                return self._once(method, path, data, sign() if sign else {}, timeout)
+            except EngineError as err:
+                wait = (
+                    self.retries.wait(
+                        attempt, err.status, err.retry_after, time.monotonic() - start
+                    )
+                    if self.retries is not None
+                    else None
+                )
+                if wait is None:
+                    raise
+                self._sleep(wait)
+                attempt += 1
+
+    def _once(
+        self,
+        method: str,
+        path: str,
+        data: bytes | None,
+        headers: dict[str, str],
+        timeout: float | None,
+    ) -> Any:
+        req = urllib.request.Request(self.engine_url + path, data=data, method=method)
+        req.add_header("Accept", "application/json")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        for k, v in headers.items():
+            req.add_header(k, v)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout or self.timeout) as res:
+                raw = res.read()
+        except urllib.error.HTTPError as err:
+            raw = err.read()
+            code, message = "http_error", err.reason or ""
+            try:
+                parsed = json.loads(raw)
+                code = parsed.get("code", code)
+                message = parsed.get("message", message)
+            except (ValueError, AttributeError):
+                if raw:
+                    message = raw.decode("utf-8", "replace")[:200]
+            failure = EngineError(err.code, str(code), str(message))
+            failure.retry_after = (
+                err.headers.get("Retry-After") if err.headers else None
+            )
+            raise failure from None
+        return json.loads(raw) if raw else None
+
+
+def resolved(decision: dict[str, Any]) -> bool:
+    """Whether the decision no longer waits for a person: anything but
+    require_approval, or an approval outcome that has been decided."""
+    if decision.get("verdict") != "require_approval":
+        return True
+    approval = decision.get("approval") or {}
+    return approval.get("status") in RESOLVED_APPROVAL