mintid-agent 0.1.0__py3-none-any.whl

mintid_agent/__init__.py

@@ -0,0 +1,89 @@
+"""mintid-agent — the MintID agent client (MINT-342).
+
+An agent runtime's side of the agent channel, over the holder library
+(``proof_core.holder``): ``AgentClient.issue_from_offer`` (the principal's
+mint presentation redeems an agent offer), ``refresh`` (status witness +
+bulk scope delta replay), ``present`` (fail closed, naming the output key),
+``pay`` (the bIP-0002/1 x402 identity loop, Web Bot Auth-signed) and
+``renew`` (MINT-19 replacement). Keys never leave the client: the
+credential's private bytes go only to an injected ``CredentialStore``
+(encrypt-at-rest is the integrator's), the signing key stays behind an
+injected ``Signer``. See ``docs/sdk/12-agent-clients.md``.
+
+The pairwise agent pseudonym (R-A10) is mandatory in every ``bip-0002/1``
+policy since contract 1.4.0: ``pay`` / ``present`` need nothing for it —
+the holder proves the pseudonym for the challenge's own verifier (and
+refuses a challenge naming another). ``unexpired`` is mandatory too since
+1.5.0 (a declaration without it is ``unexpired_required``); an agent past
+its lease cannot answer anywhere, and ``refresh`` reports the issuer's lease
+sweep as ``CredentialRevoked`` from the next root on. A vendor session ends
+with the status root it was decided under, so ``pay`` presents again after
+each new root. Not in this version: sub-delegation
+(``agent.delegate`` is gated)."""
+
+from proof_core.holder import (
+    CredentialRevoked,
+    HolderError,
+    SelfRevocationReceipt,
+    SelfRevocationRefused,
+    WitnessState,
+)
+
+from mintid_agent.client import AgentClient, Payer, PaymentResult
+from mintid_agent.errors import (
+    AgentClientError,
+    ChallengeError,
+    IdentityRefused,
+    PolicyUnsatisfiable,
+)
+from mintid_agent.issuance import redeem_agent_offer
+from mintid_agent.store import CredentialStore, MemoryStore
+from mintid_agent.web_bot_auth import (
+    Ed25519Signer,
+    Signer,
+    directory_document,
+    okp_thumbprint,
+    sign_headers,
+)
+from mintid_agent.x402 import (
+    PRESENTATION_HEADER,
+    SESSION_HEADER,
+    Http,
+    HttpResponse,
+    IdentityDeclaration,
+    encode_presentation_header,
+    urllib_http,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PRESENTATION_HEADER",
+    "SESSION_HEADER",
+    "AgentClient",
+    "AgentClientError",
+    "ChallengeError",
+    "CredentialRevoked",
+    "CredentialStore",
+    "Ed25519Signer",
+    "HolderError",
+    "Http",
+    "HttpResponse",
+    "IdentityDeclaration",
+    "IdentityRefused",
+    "MemoryStore",
+    "Payer",
+    "PaymentResult",
+    "PolicyUnsatisfiable",
+    "SelfRevocationReceipt",
+    "SelfRevocationRefused",
+    "Signer",
+    "WitnessState",
+    "__version__",
+    "directory_document",
+    "encode_presentation_header",
+    "okp_thumbprint",
+    "redeem_agent_offer",
+    "sign_headers",
+    "urllib_http",
+]

mintid_agent/client.py

@@ -0,0 +1,504 @@
+"""``AgentClient`` — one agent credential in its runtime's custody.
+
+- **Issuance** (``issue_from_offer``): the principal's mint presentation
+  redeems an agent offer; the scope witnesses are adopted with their delta
+  cursor (``issuance``). ``renew`` redeems a renewal offer (MINT-19:
+  replacement — the old credential is revoked on issuance).
+- **Freshness** (``refresh``): the status witness, then the issuer's public
+  scope delta log replayed in bulk from the cursor (``?since=<cursor>``,
+  never a per-value query — agent-presentation-v1 §6). A withdrawn
+  delegation then refuses at the holder: fail closed, no proof emitted.
+- **Presenting** (``present``): the holder library answers a §10.5
+  challenge or refuses, naming the output key (``PolicyUnsatisfiable``).
+- **Paying** (``pay``): the x402 loop of bIP-0002/1 — see ``pay``.
+- **Kill switch** (``self_revoke``): R11 self-revocation of this agent
+  credential (self-revocation-v1 §5.5), submitted through a privacy relay
+  that pays for the transaction (MINT-348); the receipt is confirmed
+  against the chain on ``chain_rpc`` (MINT-372) through the issuer-scoped
+  ``RecordedNullifiers`` read, which names no nullifier (MINT-377).
+
+Custody: the holder's private bytes stay in the holder library and reach
+only the injected ``CredentialStore`` (``store``); the Web Bot Auth key
+stays behind the injected ``Signer``. Nothing here logs or returns either.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.parse
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+
+from proof_core.chain import NullifierReader
+from proof_core.holder import (
+    Holder,
+    HolderError,
+    SelfRevocationReceipt,
+    Transport,
+    WitnessState,
+    submit_self_revocation,
+)
+
+from mintid_agent import issuance
+from mintid_agent.errors import ChallengeError, IdentityRefused, PolicyUnsatisfiable
+from mintid_agent.store import CredentialStore, CustodyRecord
+from mintid_agent.web_bot_auth import Signer, sign_headers
+from mintid_agent.x402 import (
+    PAYMENT_HEADER,
+    PRESENTATION_HEADER,
+    SESSION_HEADER,
+    Http,
+    HttpResponse,
+    IdentityDeclaration,
+    encode_presentation_header,
+    origin_of,
+    reason_of,
+    urllib_http,
+)
+
+STALE_ROOT = "status_root_stale"
+# Reasons a vendor's identity leg gives that call for a (new) presentation:
+# the session states, and the one rejection a buyer agent retries —
+# ``status_root_stale``, after a refresh. Every other rejection is terminal
+# for the attempt (bIP-0002 §10, v1 buyer agent conformance).
+REPRESENT = frozenset(
+    {
+        "identity_required",
+        "session_expired",
+        "session_key_mismatch",
+        STALE_ROOT,
+    }
+)
+MAX_PRESENTATIONS = 2  # per payment: the first, and one after a retryable answer
+
+Payer = Callable[[object], str]
+"""``payer(payment_required_body) -> X-PAYMENT value`` — the x402 payment
+scheme is the integrator's (wallet, facilitator client); the client calls it
+once per payment, and only after the identity leg can be answered."""
+
+
+@dataclass(frozen=True, slots=True)
+class PaymentResult:
+    status: int
+    headers: Mapping[str, str]
+    body: object
+    presented: bool  # a fresh presentation was sent for this payment
+    session_reused: bool  # the vendor accepted an existing session token
+    paid: bool  # an X-PAYMENT was sent
+
+
+@dataclass
+class AgentClient:
+    holder: Holder
+    credential_id: str
+    expires_at: int
+    scope_endpoint: str
+    transport: Transport
+    scope_cursor: int = 0
+    store: CredentialStore | None = None
+    http: Http | None = None
+    signer: Signer | None = None
+    signature_agent: str | None = None
+    clock: Callable[[], float] = time.time
+    sessions: dict[str, str] = field(default_factory=dict)  # authority → token
+    last_refresh: float | None = None
+    presentations: int = 0
+    # The node the kill switch confirms its receipt on (MINT-372): a CometBFT
+    # RPC URL or a ``NullifierReader``; ``None`` → ``$MINTID_CHAIN_RPC``, then
+    # ``$MINTID_RPC`` (https://rpc.anchor.mintid.net on the anchor).
+    chain_rpc: str | NullifierReader | None = None
+    # The bounded-agent bundle it was minted from (MINT-403): "" for a raw
+    # scope. Informative for the runtime; the proof is what a verifier sees.
+    bundle_id: str = ""
+
+    # ── construction ────────────────────────────────────────────────
+
+    @classmethod
+    def issue_from_offer(
+        cls,
+        offer: dict,
+        principal: Holder,
+        *,
+        transport: Transport,
+        store: CredentialStore | None = None,
+        **options,
+    ) -> AgentClient:
+        """Redeem an agent offer with the principal's holder. ``HolderError``
+        on a terminal issuer refusal, ``ValueError`` when the offer is not an
+        agent offer or the principal cannot answer the mint challenge."""
+        issued = issuance.redeem_agent_offer(offer, principal, transport=transport)
+        client = cls(
+            holder=issued.holder,
+            credential_id=issued.credential_id,
+            expires_at=issued.expires_at,
+            scope_endpoint=issued.scope_endpoint,
+            transport=transport,
+            scope_cursor=issued.scope_cursor,
+            store=store,
+            bundle_id=issued.bundle_id,
+            **options,
+        )
+        client.persist()
+        return client
+
+    @classmethod
+    def load(
+        cls,
+        credential_id: str,
+        store: CredentialStore,
+        *,
+        transport: Transport,
+        **options,
+    ) -> AgentClient:
+        """Resume a credential from the store (``KeyError`` if absent)."""
+        raw = store.load(credential_id)
+        if raw is None:
+            raise KeyError(credential_id)
+        record = CustodyRecord.from_bytes(raw)
+        return cls(
+            holder=Holder.from_storage(record.storage, transport=transport),
+            credential_id=record.credential_id,
+            expires_at=record.expires_at,
+            scope_endpoint=record.scope_endpoint,
+            transport=transport,
+            scope_cursor=record.scope_cursor,
+            store=store,
+            bundle_id=record.bundle_id,
+            **options,
+        )
+
+    def renew(self, offer: dict, principal: Holder) -> AgentClient:
+        """Redeem a renewal offer (the operator's ``…/renew``): a new client
+        for the replacement credential with this one's runtime settings.
+        The issuer revokes this credential on issuance, so its record leaves
+        the store."""
+        new = AgentClient.issue_from_offer(
+            offer,
+            principal,
+            transport=self.transport,
+            store=self.store,
+            http=self.http,
+            signer=self.signer,
+            signature_agent=self.signature_agent,
+            clock=self.clock,
+            chain_rpc=self.chain_rpc,
+        )
+        if self.store is not None:
+            self.store.delete(self.credential_id)
+        return new
+
+    def persist(self) -> None:
+        if self.store is None:
+            return
+        self.store.save(
+            self.credential_id,
+            CustodyRecord(
+                credential_id=self.credential_id,
+                expires_at=self.expires_at,
+                scope_endpoint=self.scope_endpoint,
+                scope_cursor=self.scope_cursor,
+                storage=self.holder.storage_bytes(),
+                bundle_id=self.bundle_id,
+            ).to_bytes(),
+        )
+
+    # ── freshness ───────────────────────────────────────────────────
+
+    def refresh_scope(self) -> int:
+        """Replay the issuer's public delta log after the cursor (bulk);
+        returns the last delta sequence number the log reports."""
+        parts = urllib.parse.urlsplit(self.scope_endpoint)
+        url = urllib.parse.urlunsplit(
+            parts._replace(query=urllib.parse.urlencode({"since": self.scope_cursor}))
+        )
+        status, body = self.transport("GET", url)
+        if status != 200:
+            raise HolderError("scope_deltas", status, body)
+        last = int(body["last_seq"])
+        if last > self.scope_cursor:
+            self.holder.refresh_scope(bytes.fromhex(body["log"]))
+            self.scope_cursor = last
+        return last
+
+    def refresh(self) -> WitnessState:
+        """The status witness (``CredentialRevoked`` once the agent is out of
+        the accumulator), then — once a finalized root anchors it — the
+        scope delta log. Persists the result."""
+        state = self.holder.refresh_witness()
+        if state.usable:
+            self.refresh_scope()
+        self.last_refresh = self.clock()
+        self.persist()
+        return state
+
+    # ── presenting ──────────────────────────────────────────────────
+
+    def present(self, challenge: dict) -> dict:
+        """The envelope for a verifier's §10.5 challenge (``{request,
+        signature_hex}`` or the bare request). ``PolicyUnsatisfiable``
+        (a ``ValueError``) names the output key when the credential cannot
+        satisfy the policy — nothing leaves the holder then. Call
+        ``refresh`` first (``pay`` does): the holder proves over the witness
+        material it holds, and a proof over superseded scope anchors is a
+        verifier's ``proof_invalid``, not a holder refusal."""
+        try:
+            envelope = self.holder.present(challenge)
+        except ValueError as exc:
+            raise PolicyUnsatisfiable.from_holder(exc) from exc
+        self.presentations += 1
+        return envelope
+
+    def relay_disclosure(
+        self,
+        issuer_url: str,
+        message: dict,
+        prove: Callable[[dict], object] | None = None,
+    ) -> dict:
+        """MINT-406: relay a relying party's ``DisclosureOffer`` or
+        ``IdentificationRequest`` to this agent's issuer with the relay
+        proof over the issuer's challenge. The agent grants nothing and
+        receives no field: the answer is ``{state, reason}``
+        (``mintid_agent.disclosure``).
+
+        Without ``prove`` the holder proves (MINT-409: the relay-to-issuer
+        presentation, ``Holder.present_for_relay``) after a witness
+        ``refresh`` — the proof is made against the definition the holder
+        last refreshed to, which is the one the issuer accepts."""
+        from mintid_agent.disclosure import holder_prover, relay_disclosure
+
+        if prove is None:
+            self.refresh()
+            prove = holder_prover(self.holder)
+        return relay_disclosure(issuer_url, message, prove, http=self.http)
+
+    def info(self):
+        return self.holder.info()
+
+    # ── kill switch (R11) ───────────────────────────────────────────
+
+    def self_revoke(
+        self,
+        chain_id: str,
+        anchoring: dict | None = None,
+        relay_url: str | None = None,
+        *,
+        status_root: bytes | None = None,
+        relay_transport: Transport | None = None,
+        chain: str | NullifierReader | None = None,
+        **confirm,
+    ) -> dict | SelfRevocationReceipt:
+        """The agent's own kill switch (R-A6 per-agent self-revoke, R11;
+        self-revocation-v1 §5.2, §5.5).
+
+        The holder builds and checks the SRP-1 message and from then on
+        refuses to present; the custody record is persisted *before* any
+        submission, so the refusal survives a crash. ``anchoring`` is the
+        issuer metadata's ``anchoring`` object of a root in the chain's ring
+        (its ``agent`` member is taken when present); omitted, the material
+        the last ``refresh`` cached is used (the issuer serves it with the
+        witness, MINT-347). ``status_root``, when read from the chain, must
+        be that root.
+
+        Without ``relay_url`` the message is returned (``{message,
+        nullifier, ciphertext}``) for any relay to submit — see
+        ``submit_self_revocation``. With it, the message goes straight to
+        that privacy relay (MINT-348) and the receipt is returned, confirmed
+        on the chain (MINT-372; see ``submit_self_revocation``)."""
+        material = anchoring.get("agent", anchoring) if anchoring is not None else None
+        revocation = self.holder.self_revoke(chain_id, material, status_root)
+        self.persist()
+        if relay_url is None:
+            return revocation
+        return self.submit_self_revocation(
+            relay_url,
+            revocation,
+            relay_transport=relay_transport,
+            chain=chain,
+            **confirm,
+        )
+
+    def submit_self_revocation(
+        self,
+        relay_url: str,
+        revocation: dict,
+        *,
+        relay_transport: Transport | None = None,
+        chain: str | NullifierReader | None = None,
+        **confirm,
+    ) -> SelfRevocationReceipt:
+        """Hand a ``self_revoke`` result to a privacy relay (MINT-348, §5.3)
+        over ``relay_transport`` (default: a fresh stdlib transport, never
+        ``self.transport``, which talks to the issuer), then confirm it on
+        the chain (MINT-372): the receipt is ``pending``/``folded`` only when
+        the node (``chain``, else ``chain_rpc``, else ``$MINTID_CHAIN_RPC`` /
+        ``$MINTID_RPC``) shows the nullifier — whatever the relay answered,
+        ``nullifier_recorded`` included. Otherwise it is ``submitted`` with
+        ``unconfirmed_reason``: check again, or resubmit through another
+        relay (the message is idempotent). A refusal raises
+        ``SelfRevocationRefused``; the holder keeps refusing to present
+        either way. ``confirm``: ``chain_post``, ``confirm_attempts``,
+        ``confirm_interval``, ``sleep``."""
+        return submit_self_revocation(
+            relay_url,
+            revocation,
+            transport=relay_transport,
+            chain=self.node(chain),
+            **confirm,
+        )
+
+    def node(
+        self, chain: str | NullifierReader | None = None
+    ) -> str | NullifierReader | None:
+        """The node the kill switch reads: ``chain``, else ``chain_rpc``,
+        else ``$MINTID_CHAIN_RPC``, else ``$MINTID_RPC`` (``None``: no chain
+        endpoint — the receipt stays ``submitted``)."""
+        for candidate in (
+            chain,
+            self.chain_rpc,
+            os.environ.get("MINTID_CHAIN_RPC"),
+            os.environ.get("MINTID_RPC"),
+        ):
+            if candidate:
+                return candidate
+        return None
+
+    # ── x402 ────────────────────────────────────────────────────────
+
+    def _headers(self, authority: str) -> dict[str, str]:
+        if self.signer is None:
+            return {}
+        if not self.signature_agent:
+            raise ValueError("a Web Bot Auth signer needs its signature_agent URL")
+        return sign_headers(
+            self.signer,
+            authority=authority,
+            signature_agent=self.signature_agent,
+            now=int(self.clock()),
+        )
+
+    def _send(self, method, url, authority, extra, body) -> HttpResponse:
+        http = self.http or urllib_http()
+        headers = {**self._headers(authority), **extra}
+        return http(method, url, headers=headers, body=body)
+
+    def _identity_header(
+        self, declaration: IdentityDeclaration, resource_origin: str
+    ) -> str:
+        """Refresh → challenge → local satisfiability (the holder) → header
+        value. The refresh comes first so the 10-second window is the
+        proof's alone (bIP-0002 §10: refresh before presenting)."""
+        self.refresh()
+        endpoint_origin, endpoint_authority = origin_of(declaration.challenge_endpoint)
+        resp = self._send(
+            "POST",
+            declaration.challenge_endpoint,
+            endpoint_authority,
+            {"Content-Type": "application/json"},
+            b"{}",
+        )
+        challenge = resp.body
+        if resp.status not in (200, 201) or not isinstance(challenge, dict):
+            raise ChallengeError("challenge_failed", f"HTTP {resp.status}")
+        request = challenge.get("request")
+        if not isinstance(request, dict):
+            raise ChallengeError("challenge_failed", "no request object")
+        # Present only to the party the payment is for: the resource's
+        # origin (a self-verifying seller) or the declared endpoint's (the
+        # verifying party that fronts it).
+        if request.get("audience") not in (resource_origin, endpoint_origin):
+            raise ChallengeError("audience_mismatch")
+        envelope = self.present(challenge)
+        return encode_presentation_header(request, envelope, declaration.profile)
+
+    def pay(
+        self,
+        url: str,
+        *,
+        payer: Payer,
+        method: str = "GET",
+        body: dict | bytes | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> PaymentResult:
+        """One paid request under bIP-0002/1:
+
+        request → ``402`` with ``extensions.mintid_identity`` → (no session
+        for this authority) ``POST challenge_endpoint`` → the holder proves
+        the declared policy or refuses (``PolicyUnsatisfiable``: nothing is
+        presented **and nothing is paid**) → ``payer`` builds ``X-PAYMENT``
+        → retry with ``X-PAYMENT`` + ``X-MINTID-PRESENTATION`` → on success
+        keep ``X-MINTID-SESSION`` for the authority, and send it (instead of
+        a presentation) on the next payment. The witnesses are refreshed
+        before every presentation. A session answer (``session_expired``,
+        ``identity_required``, ``session_key_mismatch``) or
+        ``status_root_stale`` (the root moved under the proof) gets one fresh
+        presentation; any other identity reason raises ``IdentityRefused``
+        (terminal for the attempt, bIP-0002 §10). Every request is Web Bot
+        Auth-signed when a signer is configured."""
+        origin, authority = origin_of(url)
+        raw = json.dumps(body).encode() if isinstance(body, dict) else body
+        base = dict(headers or {})
+        if isinstance(body, dict):
+            base.setdefault("Content-Type", "application/json")
+
+        resp = self._send(method, url, authority, base, raw)
+        if resp.status != 402:
+            return PaymentResult(
+                resp.status, resp.headers, resp.body, False, False, False
+            )
+        requirements = resp.body
+        declaration = IdentityDeclaration.from_payment_required(requirements)
+
+        payment: str | None = None
+        presented = False
+        use_session = declaration is not None and authority in self.sessions
+        fresh_presentations = 0
+        while True:
+            extra = dict(base)
+            reused = False
+            if declaration is not None:
+                if use_session:
+                    extra[SESSION_HEADER] = self.sessions[authority]
+                    reused = True
+                else:
+                    extra[PRESENTATION_HEADER] = self._identity_header(
+                        declaration, origin
+                    )
+                    presented = True
+                    fresh_presentations += 1
+            if payment is None:
+                payment = payer(requirements)
+            extra[PAYMENT_HEADER] = payment
+            resp = self._send(method, url, authority, extra, raw)
+            if resp.status != 402 or declaration is None:
+                break
+            reason = reason_of(resp.body)
+            if reason is None:
+                break  # the payment leg refused: the caller reads the 402
+            if reason not in REPRESENT or fresh_presentations >= MAX_PRESENTATIONS:
+                raise IdentityRefused(reason, resp.status, resp.body)
+            self.sessions.pop(authority, None)
+            use_session = False
+        if 200 <= resp.status < 300 and declaration is not None:
+            token = resp.header(SESSION_HEADER)
+            if token:
+                self.sessions[authority] = token
+        return PaymentResult(
+            resp.status,
+            resp.headers,
+            resp.body,
+            presented,
+            reused and 200 <= resp.status < 300,
+            True,
+        )
+
+
+__all__ = [
+    "MAX_PRESENTATIONS",
+    "REPRESENT",
+    "STALE_ROOT",
+    "AgentClient",
+    "Payer",
+    "PaymentResult",
+]