a2cn 0.3.3__py3-none-any.whl

a2cn/__init__.py

@@ -0,0 +1,40 @@
+"""A2CN reference implementation."""
+
+import json
+from importlib.metadata import PackageNotFoundError, distribution
+from pathlib import Path
+from urllib.parse import urlparse
+from urllib.request import url2pathname
+
+_SOURCE_VERSION = "0.0.0+source"
+
+
+def _installed_version() -> str:
+    """The version of the installed distribution that owns this source tree.
+
+    Another distribution named ``a2cn`` may be installed while Python imports a
+    different tree, so its version is reported only when that distribution's
+    files, or its editable install root, are the tree imported here.
+    """
+    try:
+        dist = distribution("a2cn")
+    except PackageNotFoundError:
+        return _SOURCE_VERSION
+    here = Path(__file__).resolve()
+    if Path(dist.locate_file("a2cn/__init__.py")).resolve() == here:
+        return dist.version
+    direct_url = dist.read_text("direct_url.json")
+    if direct_url:
+        info = json.loads(direct_url)
+        url = urlparse(info.get("url", ""))
+        if info.get("dir_info", {}).get("editable") and url.scheme == "file":
+            if Path(url2pathname(url.path)).resolve() == here.parent.parent:
+                return dist.version
+    return _SOURCE_VERSION
+
+
+__version__ = _installed_version()
+
+from a2cn.versions import PROTOCOL_VERSIONS  # noqa: E402
+
+__all__ = ["PROTOCOL_VERSIONS", "__version__"]

a2cn/acts.py

@@ -0,0 +1,130 @@
+"""Verify one signed act on its own (Sections 7.3 to 7.6).
+
+A record verifier checks the acts inside a record; this checks a single act an
+auditor holds by itself: an offer, counteroffer, acceptance, rejection or
+withdrawal. It rebuilds the object the act's signature covers with the same
+primitive the records use (``rebuild_signed_act``, Section 7.3.1), requires the
+signing method to be under the sender's DID, and verifies the signature against
+the key that DID document lists for it. For an offer or counteroffer the act's
+stated ``protocol_act_hash`` must also equal the rebuilt hash (Section 7.3.2).
+
+A verified act proves who signed which terms. It says nothing about the session
+around it: whether the act was in turn, in time, or ever accepted.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from jwt.exceptions import InvalidSignatureError
+
+from a2cn.crypto import hash_object, verify_jws
+from a2cn.did import (
+    VerificationMethodNotFoundError,
+    get_public_key,
+    get_verification_method,
+    require_did_document_for,
+)
+from a2cn.messages import SIGNED_ACT_SIGNATURE_FIELDS, SUPPORTED_WIRE_VERSIONS, rebuild_signed_act
+
+DidResolver = Mapping[str, dict] | Callable[[str], dict]
+
+#: The act types this verifies: every act that carries its own signature.
+SIGNED_ACT_TYPES = tuple(SIGNED_ACT_SIGNATURE_FIELDS)
+
+# Why an act does not verify. verify_signed_act_reason returns one of these, or
+# None when the act verifies.
+ACT_REASON_UNSUPPORTED_TYPE = "UNSUPPORTED_ACT_TYPE"
+ACT_REASON_VERSION_UNSTATED = "WIRE_VERSION_UNSTATED"
+ACT_REASON_NOT_RECOMPUTABLE = "ACT_NOT_RECOMPUTABLE"
+ACT_REASON_HASH_MISMATCH = "PROTOCOL_ACT_HASH_MISMATCH"
+ACT_REASON_SIGNATURE_MISSING = "SIGNATURE_MISSING"
+ACT_REASON_METHOD_NOT_CONTROLLED = "VERIFICATION_METHOD_NOT_CONTROLLED"
+ACT_REASON_KEY_NOT_FOUND = "KEY_NOT_FOUND"
+ACT_REASON_KEY_UNUSABLE = "VERIFICATION_METHOD_UNUSABLE"
+ACT_REASON_SIGNATURE_INVALID = "SIGNATURE_INVALID"
+
+
+def verify_signed_act_reason(
+    act: Any,
+    did_resolver: DidResolver,
+    *,
+    wire_version: str | None = None,
+) -> str | None:
+    """Why ``act`` does not verify, or None when its signature does.
+
+    ``wire_version`` stands in for a ``protocol_version`` the act does not state.
+    An act received inside a session states none and is rebuilt under the
+    session's negotiated version (Section 7.3.1); held on its own, nothing says
+    which version that was, so the caller must say. An act that states its
+    version is always rebuilt under it, and ``wire_version`` is then ignored.
+    """
+    if not isinstance(act, Mapping) or act.get("message_type") not in SIGNED_ACT_SIGNATURE_FIELDS:
+        return ACT_REASON_UNSUPPORTED_TYPE
+    if "protocol_version" not in act and wire_version not in SUPPORTED_WIRE_VERSIONS:
+        return ACT_REASON_VERSION_UNSTATED
+
+    rebuilt = rebuild_signed_act(act, version_when_absent=wire_version or "")
+    if rebuilt is None:
+        return ACT_REASON_NOT_RECOMPUTABLE
+    try:
+        expected_hash = hash_object(rebuilt)
+    except ValueError:
+        # A string with no UTF-8 encoding (a lone surrogate) cannot be
+        # canonicalized (RFC 8785): the act cannot be recomputed.
+        return ACT_REASON_NOT_RECOMPUTABLE
+    if act["message_type"] in ("offer", "counteroffer") and act.get("protocol_act_hash") != expected_hash:
+        return ACT_REASON_HASH_MISMATCH
+
+    signature = act.get(SIGNED_ACT_SIGNATURE_FIELDS[act["message_type"]])
+    verification_method = act.get("sender_verification_method")
+    sender_did = act.get("sender_did")
+    if not (isinstance(signature, str) and signature) or not (
+        isinstance(verification_method, str) and verification_method
+    ):
+        return ACT_REASON_SIGNATURE_MISSING
+    if not (
+        isinstance(sender_did, str)
+        and sender_did
+        and (verification_method == sender_did or verification_method.startswith(f"{sender_did}#"))
+    ):
+        return ACT_REASON_METHOD_NOT_CONTROLLED
+
+    try:
+        did_document = require_did_document_for(
+            did_resolver(sender_did) if callable(did_resolver) else did_resolver[sender_did],
+            sender_did,
+        )
+    except Exception:
+        # A DID document the resolver cannot supply is a key that is not
+        # available, exactly like one the document does not list; so is a
+        # document whose id is not sender_did (Section 4.2).
+        return ACT_REASON_KEY_NOT_FOUND
+    try:
+        method = get_verification_method(did_document, verification_method)
+    except VerificationMethodNotFoundError:
+        # The document does not list this key: rotated, or never published. The
+        # signature cannot be checked either way, which is not a refusal.
+        return ACT_REASON_KEY_NOT_FOUND
+    except Exception:
+        return ACT_REASON_KEY_UNUSABLE
+    try:
+        public_key = get_public_key(method)
+    except Exception:
+        # Listed but unreadable (a coordinate that is not unpadded base64url,
+        # an unsupported type): the key is not available, as when unlisted.
+        return ACT_REASON_KEY_NOT_FOUND
+    try:
+        signed_payload = verify_jws(signature, public_key)
+    except (InvalidSignatureError, ValueError):
+        # A signature that does not verify, or bytes that are not a JWS at all.
+        return ACT_REASON_SIGNATURE_INVALID
+    if signed_payload != expected_hash:
+        return ACT_REASON_SIGNATURE_INVALID
+    return None
+
+
+def verify_signed_act(act: Any, did_resolver: DidResolver, *, wire_version: str | None = None) -> bool:
+    """Whether ``act``'s signature verifies; ``verify_signed_act_reason`` says why not."""
+    return verify_signed_act_reason(act, did_resolver, wire_version=wire_version) is None

a2cn/client.py

@@ -0,0 +1,423 @@
+"""
+A2CN Initiator Client (Section 3.1, 6, 7)
+
+Implements the buyer-side agent:
+  - fetch_discovery
+  - initiate_session
+  - send_offer
+  - send_acceptance
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone, timedelta
+from typing import Any
+
+import httpx
+
+from a2cn.crypto import (
+    EllipticCurvePrivateKey,
+    hash_object,
+    sign_jws,
+    create_jwt,
+)
+from a2cn.messages import (
+    PROTOCOL_ACT_VERSION,
+    negotiated_protocol_version,
+    protocol_act_object,
+    signed_act_hash,
+)
+from a2cn.record import generate_transaction_record, A2CN_NAMESPACE
+from a2cn.session import (
+    A2CNError,
+    Session,
+    SessionState,
+    check_fixed_money_params,
+    check_session_versions,
+    check_offer_money_params,
+)
+
+A2CN_CONTENT_TYPE = "application/a2cn+json"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _expires_at(seconds: int) -> str:
+    t = datetime.now(timezone.utc) + timedelta(seconds=seconds)
+    return t.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class A2CNClient:
+    """
+    Buyer-side A2CN client. Holds identity info and a live httpx.AsyncClient.
+    """
+
+    def __init__(
+        self,
+        agent_info: dict,
+        private_key: EllipticCurvePrivateKey,
+        mandate: dict,
+        http_client: httpx.AsyncClient | None = None,
+        auth_token: str | None = None,  # TODO v0.3: generate DID-based JWT locally
+    ) -> None:
+        self.agent_info = agent_info
+        self.private_key = private_key
+        self.mandate = mandate
+        self._http = http_client or httpx.AsyncClient()
+        self.auth_token = auth_token
+
+        # Session state maintained by the client
+        self._sessions: dict[str, dict] = {}
+
+    def _auth_headers(self) -> dict:
+        if self.auth_token:
+            return {"Authorization": f"Bearer {self.auth_token}"}
+        return {}
+
+    async def fetch_discovery(self, base_url: str) -> dict:
+        """
+        Fetch the discovery document at {base_url}/.well-known/a2cn-agent.
+        Section 4.3.
+        """
+        url = f"{base_url}/.well-known/a2cn-agent"
+        response = await self._http.get(url)
+        response.raise_for_status()
+        return response.json()
+
+    async def initiate_session(
+        self,
+        endpoint: str,
+        responder_did: str,
+        session_params: dict,
+    ) -> dict:
+        """
+        Send a SessionInit and return the SessionAck dict.
+        Section 6.3.
+        """
+        message_id = str(uuid.uuid4())
+
+        session_init = {
+            "message_type": "session_init",
+            "message_id": message_id,
+            "protocol_version": PROTOCOL_ACT_VERSION,
+            "session_params": session_params,
+            "initiator": self.agent_info,
+            "initiator_mandate": self.mandate,
+        }
+
+        headers = {
+            "Content-Type": A2CN_CONTENT_TYPE,
+            "Idempotency-Key": message_id,
+            **self._auth_headers(),
+        }
+
+        resp = await self._http.post(
+            f"{endpoint}/sessions",
+            json=session_init,
+            headers=headers,
+        )
+        resp.raise_for_status()
+        ack = resp.json()
+        if not isinstance(ack, dict):
+            raise A2CNError("INVALID_REQUEST", "SessionAck must be a JSON object", 400)
+
+        # The responder must state the version this client proposed (Section 12.1.7),
+        # which is the current one: a live session is never established at a
+        # superseded version, so no legacy replay here (Section 11.2.1). It must
+        # also echo currency, and any basis it carries, unchanged (Section 6.4.1)
+        check_session_versions(session_init, ack)
+        check_fixed_money_params(session_params, ack.get("session_params_accepted"))
+
+        # Cache session state
+        session_id = ack["session_id"]
+        self._sessions[session_id] = {
+            "session_init": session_init,
+            "session_ack": ack,
+            "sequence_number": 0,
+            "round_number": 0,
+            "current_turn": "initiator",
+            "offer_chain": [],
+            "message_log": [],
+            "latest_offer": None,
+        }
+
+        return ack
+
+    async def send_offer(
+        self,
+        endpoint: str,
+        responder_did: str,
+        session_id: str,
+        terms: dict,
+        in_reply_to: str | None = None,
+    ) -> dict:
+        """
+        Construct, sign, and send an Offer or Counteroffer.
+        Section 7.1 + 7.3.
+        """
+        state = self._sessions[session_id]
+        # Check the terms before the counters move, so a refused offer leaves
+        # nothing to undo and the corrected one goes out in the same round (Section 7.2)
+        check_offer_money_params(
+            state["session_ack"]["session_params_accepted"], terms, session_id=session_id
+        )
+        state["sequence_number"] += 1
+        state["round_number"] += 1
+
+        round_number = state["round_number"]
+        sequence_number = state["sequence_number"]
+        message_type = "offer" if round_number == 1 else "counteroffer"
+        message_id = str(uuid.uuid4())
+        timestamp = _now()
+        expires_at = _expires_at(state["session_ack"]["session_params_accepted"]["round_timeout_seconds"])
+
+        # Build protocol act object (Section 7.3.1)
+        protocol_act = protocol_act_object(
+            protocol_version=negotiated_protocol_version(
+                state["session_init"], state["session_ack"]
+            ),
+            session_id=session_id,
+            round_number=round_number,
+            sequence_number=sequence_number,
+            message_type=message_type,
+            sender_did=self.agent_info["did"],
+            timestamp=timestamp,
+            expires_at=expires_at,
+            terms=terms,
+        )
+
+        protocol_act_hash = hash_object(protocol_act)
+        protocol_act_signature = sign_jws(
+            protocol_act_hash,
+            self.private_key,
+            kid=self.agent_info["verification_method"],
+        )
+
+        offer = {
+            "message_type": message_type,
+            "message_id": message_id,
+            "session_id": session_id,
+            "round_number": round_number,
+            "sequence_number": sequence_number,
+            "sender_did": self.agent_info["did"],
+            "sender_agent_id": self.agent_info["agent_id"],
+            "sender_verification_method": self.agent_info["verification_method"],
+            "timestamp": timestamp,
+            "expires_at": expires_at,
+            "terms": terms,
+            "protocol_act_hash": protocol_act_hash,
+            "protocol_act_signature": protocol_act_signature,
+        }
+        if in_reply_to:
+            offer["in_reply_to"] = in_reply_to
+
+        headers = {
+            "Content-Type": A2CN_CONTENT_TYPE,
+            "Idempotency-Key": message_id,
+            **self._auth_headers(),
+        }
+
+        resp = await self._http.post(
+            f"{endpoint}/sessions/{session_id}/messages",
+            json=offer,
+            headers=headers,
+        )
+        resp.raise_for_status()
+
+        state["offer_chain"].append(protocol_act_hash)
+        state["message_log"].append(offer)
+        state["latest_offer"] = offer
+
+        return resp.json()
+
+    async def send_acceptance(
+        self,
+        endpoint: str,
+        responder_did: str,
+        session_id: str,
+        offer: dict,
+    ) -> dict:
+        """
+        Sign and send an Acceptance for the given offer dict.
+        Section 7.4.
+        """
+        state = self._sessions[session_id]
+        # The offer may never have passed the receive check: a caller can hand over
+        # any dict, and a message whose message_type is not exactly offer or
+        # counteroffer is recorded unchecked. Hold its terms to the session before
+        # the counters move, so a refused acceptance leaves nothing to undo (Section 7.2)
+        check_offer_money_params(
+            state["session_ack"]["session_params_accepted"],
+            offer.get("terms"),
+            session_id=session_id,
+            message_id=offer.get("message_id"),
+        )
+        state["sequence_number"] += 1
+        sequence_number = state["sequence_number"]
+        round_number = state["round_number"]
+        message_id = str(uuid.uuid4())
+        timestamp = _now()
+
+        accepted_offer_id = offer["message_id"]
+        accepted_hash = offer["protocol_act_hash"]
+
+        acceptance = {
+            "message_type": "acceptance",
+            "message_id": message_id,
+            "session_id": session_id,
+            "in_reply_to": accepted_offer_id,
+            "round_number": round_number,
+            "sequence_number": sequence_number,
+            "accepted_offer_id": accepted_offer_id,
+            "accepted_protocol_act_hash": accepted_hash,
+            "sender_did": self.agent_info["did"],
+            "sender_agent_id": self.agent_info["agent_id"],
+            "sender_verification_method": self.agent_info["verification_method"],
+            "timestamp": timestamp,
+        }
+
+        # Signed over the act's own envelope (Section 7.3.1): the common header
+        # plus an acceptance's payload, accepted_offer_id and
+        # accepted_protocol_act_hash. The act is built first so that what is
+        # signed is rebuilt from the very message that goes on the wire.
+        acceptance["acceptance_signature"] = sign_jws(
+            signed_act_hash(
+                acceptance,
+                version_when_absent=negotiated_protocol_version(
+                    state["session_init"], state["session_ack"]
+                ),
+            ),
+            self.private_key,
+            kid=self.agent_info["verification_method"],
+        )
+
+        headers = {
+            "Content-Type": A2CN_CONTENT_TYPE,
+            "Idempotency-Key": message_id,
+            **self._auth_headers(),
+        }
+
+        resp = await self._http.post(
+            f"{endpoint}/sessions/{session_id}/messages",
+            json=acceptance,
+            headers=headers,
+        )
+        resp.raise_for_status()
+        state["message_log"].append(acceptance)
+        return resp.json()
+
+    async def get_session_state(self, endpoint: str, session_id: str) -> dict:
+        resp = await self._http.get(f"{endpoint}/sessions/{session_id}")
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_transaction_record(self, endpoint: str, session_id: str) -> dict:
+        resp = await self._http.get(f"{endpoint}/sessions/{session_id}/record")
+        resp.raise_for_status()
+        return resp.json()
+
+    def build_client_side_record(self, session_id: str) -> dict:
+        """
+        Build the transaction record from client-side state.
+        Used to assert identical record_hash with the server's record.
+        """
+        state = self._sessions[session_id]
+
+        # Build a minimal Session-like object for generate_transaction_record
+        mock_session = _MockSession(
+            session_id=session_id,
+            session_init=state["session_init"],
+            session_ack=state["session_ack"],
+            message_log=state["message_log"],
+            offer_chain=state["offer_chain"],
+        )
+        return generate_transaction_record(mock_session)
+
+    def process_incoming(self, session_id: str, message: dict) -> None:
+        """
+        Record an incoming message from the counterparty into client-side session state.
+        Must be called for every received offer/counteroffer/acceptance so that
+        build_client_side_record() produces the correct offer_chain_hash.
+        Fix 5.8: replaces manual state patching in examples.
+        """
+        if message.get("session_id") and message["session_id"] != session_id:
+            raise ValueError(
+                f"Message session_id mismatch: expected {session_id!r}, "
+                f"got {message['session_id']!r}"
+            )
+        state = self._sessions[session_id]
+        msg_type = message.get("message_type", "")
+
+        if msg_type in ("offer", "counteroffer"):
+            # The initiator is a receiver too: before recording an offer, refuse it
+            # if its terms break the session's currency or basis (Section 7.2)
+            check_offer_money_params(
+                state["session_ack"]["session_params_accepted"],
+                message.get("terms"),
+                session_id=session_id,
+                message_id=message.get("message_id"),
+            )
+
+        state["message_log"].append(message)
+
+        if msg_type in ("offer", "counteroffer"):
+            pah = message.get("protocol_act_hash")
+            if pah:
+                state["offer_chain"].append(pah)
+            state["sequence_number"] = message.get("sequence_number", state["sequence_number"])
+            state["round_number"] = message.get("round_number", state["round_number"])
+            state["latest_offer"] = message
+            # Flip turn back to initiator after a responder counteroffer
+            state["current_turn"] = "initiator"
+        elif msg_type == "acceptance":
+            state["sequence_number"] = message.get("sequence_number", state["sequence_number"])
+            state["current_turn"] = "none"
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+
+class _MockSession:
+    """Minimal Session-like object for client-side record generation."""
+
+    def __init__(
+        self,
+        session_id: str,
+        session_init: dict,
+        session_ack: dict,
+        message_log: list[dict],
+        offer_chain: list[str],
+    ) -> None:
+        self.session_id = session_id
+        self._session_init = session_init
+        self._session_ack = session_ack
+        self._message_log = message_log
+        self._offer_chain = offer_chain
+        self.state = SessionState.COMPLETED
+        self.session_created_at = session_ack.get("session_created_at", "")
+
+        # Find final offer and acceptance from message log
+        acceptance = next(
+            (m for m in reversed(message_log) if m.get("message_type") == "acceptance"),
+            None,
+        )
+        accepted_offer_id = acceptance.get("accepted_offer_id") if acceptance else None
+        final_offer = next(
+            (m for m in message_log if m.get("message_id") == accepted_offer_id),
+            None,
+        )
+
+        self._final_offer = final_offer
+        self._final_acceptance = acceptance
+        self.round_number = max(
+            (m.get("round_number", 0) for m in message_log if "round_number" in m),
+            default=0,
+        )
+
+        # Extract party info
+        self.initiator_mandate = session_init.get("initiator_mandate", {})
+        self.responder_mandate = session_ack.get("responder_mandate", {})
+        self.session_params = session_ack.get("session_params_accepted", {})