codespar 0.10.2__tar.gz → 0.11.0__tar.gz

{codespar-0.10.2 → codespar-0.11.0}/CHANGELOG.md

@@ -1,5 +1,22 @@
 # codespar (Python SDK) — CHANGELOG
 
+## 0.11.0
+
+Offline V3 mandate verification lands as the `codespar.mandate`
+submodule, in parity with `@codespar/sdk/mandate` and the CLI. See
+[codespar/codespar-core#114](https://github.com/codespar/codespar-core/pull/114).
+
+### Added
+
+- `codespar.mandate`: `decode_mandate_token` and
+  `reconstruct_signing_string` are pure stdlib; `verify_ed25519` and
+  `verify_mandate_token` verify the V3 dual Ed25519 signatures and
+  lazily import `cryptography`, raising a clear install hint when it is
+  absent. New optional extra: `pip install codespar[verify]`. The base
+  package keeps its single runtime dependency (httpx).
+- The canonical signing string is byte-locked against the platform's
+  frozen fixture, shared with the TS SDK and CLI tests.
+
 ## 0.10.0
 
 The hosted test-mode SDK surface lands across the `codespar` Python

{codespar-0.10.2 → codespar-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespar
-Version: 0.10.2
+Version: 0.11.0
 Summary: Python SDK for CodeSpar — commerce infrastructure for AI agents in Latin America.
 Project-URL: Homepage, https://codespar.dev
 Project-URL: Documentation, https://docs.codespar.dev
@@ -22,11 +22,14 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27.0
 Provides-Extra: dev
+Requires-Dist: cryptography>=42; extra == 'dev'
 Requires-Dist: mypy>=1.11; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: verify
+Requires-Dist: cryptography>=42; extra == 'verify'
 Description-Content-Type: text/markdown
 
 # codespar — Python SDK

{codespar-0.10.2 → codespar-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codespar"
-version = "0.10.2"
+version = "0.11.0"
 description = "Python SDK for CodeSpar — commerce infrastructure for AI agents in Latin America."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,10 +30,17 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# Offline V3 mandate verification (codespar.mandate) needs Ed25519, which is
+# not in the stdlib. Opt in with `pip install codespar[verify]`; the base
+# package keeps its single runtime dependency (httpx).
+verify = [
+    "cryptography>=42",
+]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "pytest-httpx>=0.30",
+    "cryptography>=42",
     "ruff>=0.6",
     "mypy>=1.11",
 ]

codespar-0.11.0/src/codespar/mandate.py

@@ -0,0 +1,320 @@
+"""
+Offline V3 mandate verification for the CodeSpar Python SDK.
+
+A third party holding only a presentation token and a raw Ed25519 public key
+(from the agent's ``did:web`` document) can reconstruct the exact signing string
+and verify the agent + issuer signatures — no CodeSpar API call. This mirrors
+``@codespar/sdk/mandate`` (TS) and ``codespar mandate verify`` (CLI); all three
+byte-lock the canonical string against the same fixture, so they cannot drift.
+
+Import it explicitly (``from codespar.mandate import verify_mandate_token``) — it
+is not re-exported from the top-level ``codespar`` namespace, keeping the crypto
+dependency out of the base import path. Decoding and signing-string
+reconstruction are pure stdlib (zero dependencies). Ed25519 *verification* needs
+the optional ``cryptography`` extra::
+
+    pip install 'codespar[verify]'
+
+``verify_ed25519`` / ``verify_mandate_token`` (when given a key) raise a clear
+``RuntimeError`` if that extra is not installed.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = [
+    "DecodedMandateToken",
+    "MandateDecodeError",
+    "MandateVerification",
+    "SignatureCheck",
+    "agent_did_from_kid",
+    "decode_mandate_token",
+    "reconstruct_signing_string",
+    "verify_ed25519",
+    "verify_mandate_token",
+]
+
+
+class MandateDecodeError(ValueError):
+    """Raised when a token is not a well-formed mandate presentation token.
+
+    The message is the stable machine code: ``invalid_payload`` or
+    ``mandate_format_unsupported``.
+    """
+
+
+@dataclass
+class DecodedMandateToken:
+    """A decoded token: the signed fields plus the signature envelope."""
+
+    mandate: dict[str, Any]
+    # Org-HMAC hex digest. Present on every version; NOT offline-verifiable
+    # (needs the org secret) — carried through for completeness.
+    signature: str
+    agent_sig: str | None = None
+    issuer_sig: str | None = None
+    kid: str | None = None
+
+
+@dataclass
+class SignatureCheck:
+    """Per-signature outcome. ``skipped`` = present but no key supplied."""
+
+    present: bool
+    # "verified" | "failed" | "skipped" | "absent"
+    status: str
+    kid: str | None = None
+
+
+@dataclass
+class MandateVerification:
+    """Result of :func:`verify_mandate_token`."""
+
+    verified: bool
+    mandate: dict[str, Any]
+    agent: SignatureCheck
+    issuer: SignatureCheck
+    agent_did: str | None = None
+    kid: str | None = None
+
+
+def _b64url_decode(s: str) -> bytes:
+    # Node emits base64url without padding; restore it before decoding.
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def _s(value: Any) -> str:
+    # Absent optional fields render as the empty string so the separator count
+    # stays invariant — never the literal "None".
+    return "" if value is None else str(value)
+
+
+def _is_valid_fields(r: dict[str, Any]) -> bool:
+    version = r.get("format_version")
+    if not isinstance(version, int) or isinstance(version, bool):
+        return False
+    if not isinstance(r.get("id"), str):
+        return False
+    if not isinstance(r.get("agent_id"), str):
+        return False
+    if r.get("type") not in ("payment", "subscription", "delegation"):
+        return False
+    if not isinstance(r.get("amount"), str):
+        return False
+    if not isinstance(r.get("currency"), str):
+        return False
+    if not isinstance(r.get("purposes"), list):
+        return False
+    expires_at = r.get("expires_at")
+    if not isinstance(expires_at, int) or isinstance(expires_at, bool):
+        return False
+    secret_version = r.get("secret_version")
+    if not isinstance(secret_version, int) or isinstance(secret_version, bool):
+        return False
+    # V3 binds the KYC'd principal and the signing key into the signed string.
+    if version == 3:
+        if not isinstance(r.get("principal_kyc_ref"), str):
+            return False
+        if not isinstance(r.get("agent_kid"), str):
+            return False
+    return True
+
+
+def decode_mandate_token(token: str) -> DecodedMandateToken:
+    """Decode a base64url JSON presentation token.
+
+    Splits the envelope (``signature`` / ``agent_sig`` / ``issuer_sig`` / ``kid``)
+    from the signed fields so ``mandate`` is exactly the field set the signatures
+    cover. Does not verify anything. Raises :class:`MandateDecodeError` on a
+    malformed or unsupported token.
+    """
+    try:
+        raw = json.loads(_b64url_decode(token).decode("utf-8"))
+    except Exception as exc:
+        raise MandateDecodeError("invalid_payload") from exc
+
+    if not isinstance(raw, dict):
+        raise MandateDecodeError("invalid_payload")
+
+    version = raw.get("format_version")
+    if not isinstance(version, int) or isinstance(version, bool) or version < 2:
+        raise MandateDecodeError("mandate_format_unsupported")
+
+    if not _is_valid_fields(raw):
+        raise MandateDecodeError("invalid_payload")
+
+    signature = raw.get("signature")
+    if not isinstance(signature, str):
+        raise MandateDecodeError("invalid_payload")
+
+    envelope = {"signature", "agent_sig", "issuer_sig", "kid"}
+    mandate: dict[str, Any] = {k: v for k, v in raw.items() if k not in envelope}
+
+    def _str_or_none(key: str) -> str | None:
+        value = raw.get(key)
+        return value if isinstance(value, str) else None
+
+    return DecodedMandateToken(
+        mandate=mandate,
+        signature=signature,
+        agent_sig=_str_or_none("agent_sig"),
+        issuer_sig=_str_or_none("issuer_sig"),
+        kid=_str_or_none("kid"),
+    )
+
+
+def reconstruct_signing_string(fields: dict[str, Any]) -> str:
+    r"""Reconstruct the canonical signing string the Ed25519 signatures cover.
+
+    Field order (V3 = 14 fields, 13 ``:`` separators): V2's 12 fields then the
+    two V3-only fields (``principal_kyc_ref``, ``agent_kid``). Absent optionals
+    render empty; ``purposes`` is comma-joined after a lexicographic sort with
+    escaping (``\`` -> ``\\`` first, then ``,`` -> ``\,``). Colons inside
+    ``agent_kid`` (from ``did:web``) are emitted verbatim. The V3 tail is
+    appended only for ``format_version >= 3``.
+    """
+
+    def esc(member: str) -> str:
+        return member.replace("\\", "\\\\").replace(",", "\\,")
+
+    purposes = ",".join(esc(p) for p in sorted(fields.get("purposes") or []))
+    version = int(fields.get("format_version") or 0)
+    parts = [
+        str(fields.get("format_version")),
+        _s(fields.get("id")),
+        _s(fields.get("agent_id")),
+        _s(fields.get("type")),
+        _s(fields.get("amount")),
+        _s(fields.get("currency")),
+        purposes,
+        str(fields.get("expires_at")),
+        _s(fields.get("max_amount")),
+        _s(fields.get("parent_id")),
+        _s(fields.get("denomination")),
+        str(fields.get("secret_version")),
+    ]
+    if version >= 3:
+        parts.append(_s(fields.get("principal_kyc_ref")))
+        parts.append(_s(fields.get("agent_kid")))
+    return ":".join(parts)
+
+
+def verify_ed25519(signing_string: str, signature_b64url: str, pubkey: bytes) -> bool:
+    """Verify an Ed25519 signature (base64url) over a signing string.
+
+    Uses only the raw 32-byte public key. Returns ``False`` — never raises — on a
+    bad signature or malformed key. Requires the optional ``cryptography``
+    dependency; raises ``RuntimeError`` with install guidance if it is absent.
+    """
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+            Ed25519PublicKey,
+        )
+    except ImportError as exc:
+        raise RuntimeError(
+            "Ed25519 verification requires the optional 'cryptography' dependency. "
+            "Install it with: pip install 'codespar[verify]'"
+        ) from exc
+
+    try:
+        key = Ed25519PublicKey.from_public_bytes(pubkey)
+    except Exception:
+        # A malformed key is a verification failure, not an error.
+        return False
+    try:
+        key.verify(_b64url_decode(signature_b64url), signing_string.encode("utf-8"))
+        return True
+    except InvalidSignature:
+        return False
+
+
+def _to_pubkey(key: str | bytes | bytearray | None) -> bytes | None:
+    if key is None:
+        return None
+    if isinstance(key, str):
+        clean = key.strip().lower()
+        if clean.startswith("0x"):
+            clean = clean[2:]
+        if len(clean) != 64 or any(c not in "0123456789abcdef" for c in clean):
+            return None
+        return bytes.fromhex(clean)
+    raw = bytes(key)
+    return raw if len(raw) == 32 else None
+
+
+def agent_did_from_kid(kid: str) -> str:
+    """Strip the ``#<fragment>`` from an agent key id to recover the bare DID."""
+    idx = kid.find("#")
+    return kid if idx == -1 else kid[:idx]
+
+
+def _check_signature(
+    signing_string: str,
+    sig: str | None,
+    pubkey: bytes | None,
+    kid: str | None,
+) -> SignatureCheck:
+    if sig is None:
+        return SignatureCheck(present=False, status="absent", kid=kid)
+    if pubkey is None:
+        return SignatureCheck(present=True, status="skipped", kid=kid)
+    ok = verify_ed25519(signing_string, sig, pubkey)
+    return SignatureCheck(present=True, status="verified" if ok else "failed", kid=kid)
+
+
+def verify_mandate_token(
+    token: str,
+    *,
+    agent_public_key: str | bytes | bytearray | None = None,
+    issuer_public_key: str | bytes | bytearray | None = None,
+) -> MandateVerification:
+    """Offline-verify a V3 mandate presentation token against supplied keys.
+
+    Pure and network-free: pass the agent and/or issuer public keys (hex string
+    or raw bytes, from their ``did:web`` documents). A signature with a supplied
+    key that validates is ``verified``; a supplied key that fails is ``failed``;
+    a carried signature with no supplied key is ``skipped``; a signature the
+    token does not carry is ``absent``. ``verified`` is ``True`` iff at least one
+    signature verified and none failed.
+
+    Raises :class:`MandateDecodeError` on an undecodable token, and
+    ``RuntimeError`` if a key is supplied but the ``cryptography`` extra is not
+    installed.
+    """
+    decoded = decode_mandate_token(token)
+    mandate = decoded.mandate
+    signing_string = reconstruct_signing_string(mandate)
+
+    kid_value = decoded.kid or mandate.get("agent_kid")
+    kid = kid_value if isinstance(kid_value, str) else None
+    agent_did = agent_did_from_kid(kid) if kid is not None else None
+
+    agent = _check_signature(
+        signing_string,
+        decoded.agent_sig,
+        _to_pubkey(agent_public_key),
+        kid,
+    )
+    issuer = _check_signature(
+        signing_string,
+        decoded.issuer_sig,
+        _to_pubkey(issuer_public_key),
+        None,
+    )
+
+    any_verified = agent.status == "verified" or issuer.status == "verified"
+    any_failed = agent.status == "failed" or issuer.status == "failed"
+
+    return MandateVerification(
+        verified=any_verified and not any_failed,
+        mandate=mandate,
+        agent=agent,
+        issuer=issuer,
+        agent_did=agent_did,
+        kid=kid,
+    )

codespar-0.11.0/tests/_fixtures/canonical.v3.fixture.json

@@ -0,0 +1,28 @@
+{
+  "_comment": "Build 2 V3 byte-frozen fixture. DO NOT CHANGE. Mirrors canonical.fixture.json for V3 (14 fields, 13 separators = V2's 12 + principal_kyc_ref + agent_kid). HMAC key is the same test key; Ed25519 seeds are sha256('codespar-build2-agent-key-fixture') and sha256('codespar-build2-issuer-key-fixture'). Ed25519 is deterministic (RFC 8032) so agent_sig/issuer_sig are frozen. agent_kid intentionally contains colons (did:web) to pin the colon-in-final-field behaviour.",
+  "key": "test-fixture-key-do-not-use-in-prod-0123456789abcdef",
+  "input": {
+    "format_version": 3,
+    "id": "mnd_v3_abc...",
+    "agent_id": "a1",
+    "type": "delegation",
+    "amount": "5000",
+    "currency": "BRL",
+    "purposes": ["refund", "utility"],
+    "expires_at": 1735689600,
+    "max_amount": null,
+    "parent_id": null,
+    "denomination": null,
+    "secret_version": 1,
+    "principal_kyc_ref": "kyc_celcoin_11144477735",
+    "agent_kid": "did:web:id.codespar.dev:org_demo:a1#1"
+  },
+  "canonical_string": "3:mnd_v3_abc...:a1:delegation:5000:BRL:refund,utility:1735689600::::1:kyc_celcoin_11144477735:did:web:id.codespar.dev:org_demo:a1#1",
+  "hmac_sha256_hex": "4e627ac1074f1c15684cb10d63b1d4481fbeda8f82450f26c04b7860210fc3e4",
+  "agent_seed_hex": "1050a34bae067327e59c1ac43f3a25190a582448219521d35d000650d714ec9a",
+  "agent_pubkey_hex": "70940e2c00698a520339c07332ff35c05cad7b39d024a4f4737310e740b2ecc3",
+  "issuer_seed_hex": "23dddf5e3a0038f1a81cda29dbbd5d1c97d434a6610a814d3d628f7b269d031f",
+  "issuer_pubkey_hex": "41826edefd6d40fd7c32dd63ebcc0476e4324cd6a424881c53f170fee9865b14",
+  "agent_sig_b64url": "F9V0rSsfT1IjeF_4_9pciIV7w2ERdLN5r-UMkCdQWjce9ouYYY2awrrjFw5cENKbTEw0l61HitYPO5ZocfQ7Bg",
+  "issuer_sig_b64url": "ClsA7hWq1fBAG-qrhYAahDPm0xMdPl5lOJ6X0KxSzruJ2kD6NCzH-baSbxcwTxTCkWd1eBpJVke3onUR6mH1Ag"
+}

codespar-0.11.0/tests/test_mandate.py

@@ -0,0 +1,217 @@
+"""
+Offline V3 mandate verification (``codespar.mandate``).
+
+Byte-locks the canonical signing string against the shared freeze at
+``tests/_fixtures/canonical.v3.fixture.json`` — the same JSON the enterprise
+codec, the TS SDK, and the CLI pin — so the four implementations cannot drift.
+
+Decode + reconstruction are pure stdlib and always run. Ed25519 verification
+needs the optional ``cryptography`` extra; those tests skip when it is absent
+(``pip install codespar[verify]`` / the ``dev`` extra installs it in CI).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from codespar.mandate import (
+    MandateDecodeError,
+    agent_did_from_kid,
+    decode_mandate_token,
+    reconstruct_signing_string,
+    verify_ed25519,
+    verify_mandate_token,
+)
+
+FIXTURE_PATH = Path(__file__).parent / "_fixtures" / "canonical.v3.fixture.json"
+FX: dict[str, Any] = json.loads(FIXTURE_PATH.read_text())
+
+try:
+    import cryptography  # noqa: F401
+
+    HAS_CRYPTO = True
+except ImportError:
+    HAS_CRYPTO = False
+
+requires_crypto = pytest.mark.skipif(
+    not HAS_CRYPTO,
+    reason="offline verify needs the optional 'cryptography' extra (pip install codespar[verify])",
+)
+
+
+def _make_token(fields: dict[str, Any], **envelope: Any) -> str:
+    raw = json.dumps({**fields, **envelope}).encode("utf-8")
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+TOKEN = _make_token(
+    FX["input"],
+    signature=FX["hmac_sha256_hex"],
+    agent_sig=FX["agent_sig_b64url"],
+    issuer_sig=FX["issuer_sig_b64url"],
+    kid=FX["input"]["agent_kid"],
+)
+
+
+# ── decode ────────────────────────────────────────────────────────────
+
+
+def test_decode_round_trips_envelope_and_splits_signed_fields() -> None:
+    dec = decode_mandate_token(TOKEN)
+    assert dec.signature == FX["hmac_sha256_hex"]
+    assert dec.agent_sig == FX["agent_sig_b64url"]
+    assert dec.issuer_sig == FX["issuer_sig_b64url"]
+    assert dec.kid == FX["input"]["agent_kid"]
+    for leaked in ("signature", "agent_sig", "issuer_sig", "kid"):
+        assert leaked not in dec.mandate
+    assert dec.mandate["principal_kyc_ref"] == FX["input"]["principal_kyc_ref"]
+
+
+def test_decode_rejects_garbage() -> None:
+    with pytest.raises(MandateDecodeError, match="invalid_payload"):
+        decode_mandate_token("!!!nope!!!")
+
+
+def test_decode_rejects_unsupported_version() -> None:
+    bad = _make_token({**FX["input"], "format_version": 1}, signature="x")
+    with pytest.raises(MandateDecodeError, match="mandate_format_unsupported"):
+        decode_mandate_token(bad)
+
+
+def test_decode_rejects_v3_missing_required_fields() -> None:
+    fields = {k: v for k, v in FX["input"].items() if k not in ("principal_kyc_ref", "agent_kid")}
+    with pytest.raises(MandateDecodeError, match="invalid_payload"):
+        decode_mandate_token(_make_token(fields, signature="x"))
+
+
+# ── reconstruct (byte-lock) ───────────────────────────────────────────
+
+
+def test_reconstruct_is_byte_identical_to_frozen_canonical_string() -> None:
+    assert reconstruct_signing_string(FX["input"]) == FX["canonical_string"]
+
+
+def test_reconstruct_sorts_and_escapes_purposes() -> None:
+    fields = {**FX["input"], "purposes": ["utility", "refund"]}
+    assert reconstruct_signing_string(fields) == FX["canonical_string"]
+
+
+def test_reconstruct_from_decoded_mandate_matches() -> None:
+    dec = decode_mandate_token(TOKEN)
+    assert reconstruct_signing_string(dec.mandate) == FX["canonical_string"]
+
+
+# ── helpers ───────────────────────────────────────────────────────────
+
+
+def test_agent_did_from_kid_strips_fragment() -> None:
+    assert agent_did_from_kid("did:web:id.codespar.dev:org_demo:a1#1") == (
+        "did:web:id.codespar.dev:org_demo:a1"
+    )
+    assert agent_did_from_kid("did:web:x") == "did:web:x"
+
+
+def test_verify_with_no_keys_skips_and_is_not_verified() -> None:
+    res = verify_mandate_token(TOKEN)
+    assert res.agent.status == "skipped"
+    assert res.issuer.status == "skipped"
+    assert res.verified is False
+    assert res.agent_did == "did:web:id.codespar.dev:org_demo:a1"
+    assert res.kid == FX["input"]["agent_kid"]
+
+
+@pytest.mark.skipif(HAS_CRYPTO, reason="only meaningful when cryptography is absent")
+def test_verify_without_cryptography_raises_helpful_error() -> None:
+    with pytest.raises(RuntimeError, match="cryptography"):
+        verify_mandate_token(TOKEN, agent_public_key=FX["agent_pubkey_hex"])
+
+
+# ── Ed25519 verification (optional extra) ─────────────────────────────
+
+
+@requires_crypto
+def test_verify_ed25519_agent_and_issuer() -> None:
+    agent = bytes.fromhex(FX["agent_pubkey_hex"])
+    issuer = bytes.fromhex(FX["issuer_pubkey_hex"])
+    assert verify_ed25519(FX["canonical_string"], FX["agent_sig_b64url"], agent) is True
+    assert verify_ed25519(FX["canonical_string"], FX["issuer_sig_b64url"], issuer) is True
+
+
+@requires_crypto
+def test_verify_ed25519_tamper_and_wrong_key_fail() -> None:
+    agent = bytes.fromhex(FX["agent_pubkey_hex"])
+    issuer = bytes.fromhex(FX["issuer_pubkey_hex"])
+    forged = reconstruct_signing_string({**FX["input"], "amount": "9999"})
+    assert verify_ed25519(forged, FX["agent_sig_b64url"], agent) is False
+    assert verify_ed25519(FX["canonical_string"], FX["agent_sig_b64url"], issuer) is False
+    assert verify_ed25519(FX["canonical_string"], FX["agent_sig_b64url"], b"\x00" * 5) is False
+
+
+@requires_crypto
+def test_verify_mandate_token_both_signatures() -> None:
+    res = verify_mandate_token(
+        TOKEN,
+        agent_public_key=FX["agent_pubkey_hex"],
+        issuer_public_key=FX["issuer_pubkey_hex"],
+    )
+    assert res.verified is True
+    assert res.agent.status == "verified"
+    assert res.issuer.status == "verified"
+    assert res.agent.kid == FX["input"]["agent_kid"]
+    assert res.mandate["amount"] == "5000"
+
+
+@requires_crypto
+def test_verify_mandate_token_accepts_raw_bytes_keys() -> None:
+    res = verify_mandate_token(
+        TOKEN,
+        agent_public_key=bytes.fromhex(FX["agent_pubkey_hex"]),
+        issuer_public_key=bytes.fromhex(FX["issuer_pubkey_hex"]),
+    )
+    assert res.verified is True
+
+
+@requires_crypto
+def test_verify_mandate_token_agent_only_skips_issuer() -> None:
+    res = verify_mandate_token(TOKEN, agent_public_key=FX["agent_pubkey_hex"])
+    assert res.agent.status == "verified"
+    assert res.issuer.status == "skipped"
+    assert res.verified is True
+
+
+@requires_crypto
+def test_verify_mandate_token_wrong_key_fails() -> None:
+    res = verify_mandate_token(TOKEN, agent_public_key=FX["issuer_pubkey_hex"])
+    assert res.agent.status == "failed"
+    assert res.verified is False
+
+
+@requires_crypto
+def test_verify_mandate_token_tampered_fails() -> None:
+    tampered = _make_token(
+        {**FX["input"], "amount": "9999"},
+        signature=FX["hmac_sha256_hex"],
+        agent_sig=FX["agent_sig_b64url"],
+        issuer_sig=FX["issuer_sig_b64url"],
+        kid=FX["input"]["agent_kid"],
+    )
+    res = verify_mandate_token(
+        tampered,
+        agent_public_key=FX["agent_pubkey_hex"],
+        issuer_public_key=FX["issuer_pubkey_hex"],
+    )
+    assert res.verified is False
+    assert res.agent.status == "failed"
+    assert res.issuer.status == "failed"
+
+
+@requires_crypto
+def test_verify_mandate_token_malformed_hex_key_is_skipped() -> None:
+    res = verify_mandate_token(TOKEN, agent_public_key="xyz")
+    assert res.agent.status == "skipped"
+    assert res.verified is False