cowboy-protocol-py 0.6.0__py3-none-any.whl

cowboy_protocol/__init__.py

@@ -0,0 +1,458 @@
+"""``cowboy_protocol`` — the canonical Cowboy transaction codec for Python.
+
+A thin, pure-Python wrapper (no compiler at install) that loads the WS-A
+``cowboy-protocol-wasm-ffi`` ``.wasm`` via the ``wasmtime`` pip package and
+exposes a Pythonic API. It is the Python analog of ``@cowboyinc/protocol-wasm``:
+every byte and every signature comes from the SAME ``cowboy-protocol-codec``
+compiled to wasm, so ``python == native == wasm == ts`` (byte-identical, proven
+by the golden gate).
+
+This package lives **in** ``cowboyinc/core`` (``protocol/bindings/python``),
+co-located and versioned with the wasm + its flat ABI, so the ABI and its only
+Python consumer can never drift across repos.
+
+Example
+-------
+>>> import cowboy_protocol as cp
+>>> tx = '{"chain_id": 42, "nonce": 0, ...}'   # canyon-JSON tx shape
+>>> cp.signing_hash_hex(tx)
+'…64 hex chars…'
+>>> priv = bytes.fromhex("01" * 32)
+>>> cp.address_from_private_key(priv)
+'0x…EIP-55 checksum…'
+>>> signed_tx_json = cp.sign_transaction(tx, priv)
+
+The ``tx_json`` argument is the canyon-JSON transaction shape — byte-for-byte
+the same serde form node serializes, identical to the golden vectors'
+``input.json`` (see ``crates/cowboy-protocol-codec/fixtures/commonware-codec/``).
+
+On any wasm error (malformed JSON, bad key, etc.) the wrapper reads the wasm's
+``cpw_last_error`` and raises :class:`CowboyProtocolError` — it never returns
+garbage.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import json
+
+from . import error_codes  # noqa: F401
+from ._host import CowboyProtocolError, host
+
+__all__ = [
+    # COW-2792 canonical error-code registry submodule.
+    "error_codes",
+    "CowboyProtocolError",
+    "provenance",
+    "signing_preimage",
+    "signing_hash",
+    "signing_hash_hex",
+    "encode_transaction",
+    "encode_submission",
+    "sign",
+    "sign_transaction",
+    "address_from_private_key",
+    "normalize_job_request",
+    "encode_job_spec_json",
+    "decode_job_spec_to_json",
+    "validate_job_spec_bytes",
+    "validate_job_spec_json",
+    # RAS consensus-auth signing bytes (COW-2636).
+    "owner_authorization_signing_bytes",
+    "owner_delegation_signing_bytes",
+    "relay_authorization_signing_bytes",
+    # CBFS control-plane signing bytes + the delegation-cert hash (COW-2649).
+    "delegation_cert_signing_bytes",
+    "delegation_cert_hash",
+    "owner_cap_token_signing_bytes",
+    "delegated_request_signing_bytes",
+    "relay_usage_signing_bytes",
+]
+
+__version__ = "0.6.0"
+
+
+def provenance() -> dict:
+    """The build record shipped with this package (``_provenance.json``).
+
+    Says which wasm this distribution carries (``wasm.sha256`` / ``wasm.size``),
+    the JobSpec version it emits, the toolchain that built it and a digest of
+    the codec sources it was built from. ``source_revision`` is the release
+    commit, written when a release is built; it is ``None`` in a checkout. A
+    consumer can compare this record with the bundled wasm's actual hash.
+    """
+    return json.loads(
+        importlib.resources.files(__package__)
+        .joinpath("_provenance.json")
+        .read_text(encoding="utf-8")
+    )
+
+
+def _tx_bytes(tx_json: str) -> bytes:
+    """Encode a canyon-JSON tx string as UTF-8 for the ABI boundary."""
+    if not isinstance(tx_json, str):
+        raise TypeError(f"tx_json must be str, got {type(tx_json).__name__}")
+    return tx_json.encode("utf-8")
+
+
+def signing_preimage(tx_json: str) -> bytes:
+    """Return the raw bytes of ``tx.signing_preimage()``.
+
+    The canonical encoding with all signatures zeroed and a leading
+    ``CURRENT_TX_VERSION`` byte. ``tx_json`` is the canyon-JSON tx shape.
+    """
+    return host().call("cpw_signing_preimage", _tx_bytes(tx_json))
+
+
+def signing_hash(tx_json: str) -> bytes:
+    """Return the 32-byte ``tx.signing_hash()`` (``keccak256(signing_preimage())``)."""
+    return host().call("cpw_signing_hash", _tx_bytes(tx_json))
+
+
+def signing_hash_hex(tx_json: str) -> str:
+    """Return ``tx.signing_hash()`` as lowercase hex (no ``0x`` prefix)."""
+    return host().call("cpw_signing_hash_hex", _tx_bytes(tx_json)).decode("ascii")
+
+
+def encode_transaction(tx_json: str) -> bytes:
+    """Return the full canonical tx encoding (signatures included, leading version)."""
+    return host().call("cpw_encode_transaction", _tx_bytes(tx_json))
+
+
+def encode_submission(tx_json: str) -> bytes:
+    """Return the ``POST /submit`` body: ``Submission::Transactions(vec![tx]).encode()``.
+
+    The single-tx on-chain submission envelope (native commonware-codec).
+    """
+    return host().call("cpw_encode_submission", _tx_bytes(tx_json))
+
+
+def _require_key(priv_key32: bytes) -> bytes:
+    """Validate the caller-supplied 32-byte private key buffer."""
+    if not isinstance(priv_key32, (bytes, bytearray)):
+        raise TypeError(
+            f"priv_key32 must be bytes, got {type(priv_key32).__name__}"
+        )
+    if len(priv_key32) != 32:
+        raise ValueError(
+            f"priv_key32 must be exactly 32 bytes, got {len(priv_key32)}"
+        )
+    return bytes(priv_key32)
+
+
+def sign(hash32: bytes, priv_key32: bytes) -> bytes:
+    """Sign a 32-byte hash, returning a 65-byte ``r || s || v`` signature.
+
+    RFC-6979 deterministic, low-S normalized, Ethereum recovery id. ``hash32``
+    is typically the output of :func:`signing_hash`.
+
+    SECURITY: the private key is passed into wasm and lives in the host's linear
+    memory for the call (the weaker threat model accepted for COW-2363). Do not
+    feed high-value keys to this in-process signer in an untrusted host.
+    """
+    if not isinstance(hash32, (bytes, bytearray)):
+        raise TypeError(f"hash32 must be bytes, got {type(hash32).__name__}")
+    if len(hash32) != 32:
+        raise ValueError(f"hash32 must be exactly 32 bytes, got {len(hash32)}")
+    key = _require_key(priv_key32)
+    # cpw_sign input = hash(32) || key(32)
+    return host().call("cpw_sign", bytes(hash32) + key)
+
+
+def sign_transaction(tx_json: str, priv_key32: bytes) -> str:
+    """Sign a transaction and return the signed tx as canyon-JSON.
+
+    Sets ``from`` from the derived address and the primary ``signature``
+    (single-signer path; mirrors ``-codec``'s ``Transaction::sign``). For
+    multi-signer txs, assemble client-side with :func:`sign` +
+    :func:`encode_submission`.
+
+    SECURITY: see :func:`sign` — the private key lives in wasm linear memory.
+    """
+    key = _require_key(priv_key32)
+    # cpw_sign_transaction input = key(32) || json
+    out = host().call("cpw_sign_transaction", key + _tx_bytes(tx_json))
+    return out.decode("utf-8")
+
+
+def address_from_private_key(priv_key32: bytes) -> str:
+    """Return the EIP-55 checksummed address (``0x…``) for a 32-byte private key.
+
+    SECURITY: see :func:`sign` — the private key lives in wasm linear memory.
+    """
+    key = _require_key(priv_key32)
+    return host().call("cpw_address_from_private_key", key).decode("utf-8")
+
+
+# ─── JobSpec bridges (COW-2440 slice-4 Part A) ──────────────────────────────
+#
+# These marshal the canyon-JSON `JobRequest`/`JobSpec` boundary <-> the
+# canonical commonware-codec `JobSpec` bytes. ALL normalize/validate/encode
+# LOGIC lives in `-codec`'s `job_spec` module; this wrapper (like the wasm
+# bridge it calls) only (de)serializes and calls it — no protocol logic here
+# either. See the crate-level ABI doc in
+# ``crates/cowboy-protocol-wasm-ffi/src/lib.rs`` for the verbatim contract.
+
+
+def normalize_job_request(request_json: str) -> bytes:
+    """Normalize a friendly ``JobRequest`` JSON document into canonical bytes.
+
+    ``request_json`` is a ``JobRequest`` JSON document (UTF-8 on the wire).
+    Returns ``normalize(request).encode()`` — the canonical ``JobSpec`` bytes.
+
+    Raises :class:`CowboyProtocolError` on malformed JSON, or the (currently
+    infallible-in-practice) ``ValidationError`` ``normalize`` itself can
+    return.
+    """
+    if not isinstance(request_json, str):
+        raise TypeError(
+            f"request_json must be str, got {type(request_json).__name__}"
+        )
+    return host().call("cpw_normalize_job_request", request_json.encode("utf-8"))
+
+
+def encode_job_spec_json(spec_json: str) -> bytes:
+    """Encode a ``JobSpec`` JSON document into canonical bytes.
+
+    ``spec_json`` is a ``JobSpec`` JSON document (UTF-8 on the wire). Returns
+    ``spec.encode()`` — the canonical ``JobSpec`` bytes.
+
+    Raises :class:`CowboyProtocolError` on malformed/incomplete JSON.
+    """
+    if not isinstance(spec_json, str):
+        raise TypeError(f"spec_json must be str, got {type(spec_json).__name__}")
+    return host().call("cpw_encode_job_spec_json", spec_json.encode("utf-8"))
+
+
+def decode_job_spec_to_json(spec_bytes: bytes) -> str:
+    """Decode canonical ``JobSpec`` bytes and re-serialize them as JSON.
+
+    ``spec_bytes`` must be ``JobSpec::decode_canonical``-valid canonical bytes
+    (e.g. the output of :func:`normalize_job_request` or
+    :func:`encode_job_spec_json`).
+
+    Raises :class:`CowboyProtocolError` if the bytes fail ``decode_canonical``
+    (bad version byte, trailing bytes, a truncated field, an over-cap length
+    prefix, ...).
+    """
+    if not isinstance(spec_bytes, (bytes, bytearray)):
+        raise TypeError(
+            f"spec_bytes must be bytes, got {type(spec_bytes).__name__}"
+        )
+    return host().call("cpw_decode_job_spec_to_json", bytes(spec_bytes)).decode(
+        "utf-8"
+    )
+
+
+def validate_job_spec_bytes(spec_bytes: bytes) -> bytes:
+    """Run ``-codec``'s ``validate()`` over canonical ``JobSpec`` bytes.
+
+    ``spec_bytes`` must be ``JobSpec::decode_canonical``-valid canonical
+    bytes.
+
+    **Verdict convention**: the return value is itself the verdict, NOT a
+    boolean. A validation VERDICT (accept or reject) is always a
+    success-path result:
+
+      * **empty bytes (``b""``) = ACCEPT** — the spec passed ``validate()``.
+      * **non-empty bytes = REJECT** — a UTF-8 JSON object
+        ``{"code", "field", "message"}`` (the ``ValidationError``'s own
+        fields) describing why ``validate()`` rejected the spec.
+
+    A :class:`CowboyProtocolError` is raised ONLY when the input does not
+    even decode into a well-formed ``JobSpec`` (a decode failure is a
+    distinct, FFI-level error from a well-formed spec that ``validate()``
+    rejects — see the crate doc's ``cpw_validate_job_spec_bytes`` entry).
+    """
+    if not isinstance(spec_bytes, (bytes, bytearray)):
+        raise TypeError(
+            f"spec_bytes must be bytes, got {type(spec_bytes).__name__}"
+        )
+    return host().call("cpw_validate_job_spec_bytes", bytes(spec_bytes))
+
+
+def validate_job_spec_json(spec_json: str) -> bytes:
+    """Run ``-codec``'s ``validate()`` over a ``JobSpec`` JSON document.
+
+    Same **verdict convention** as :func:`validate_job_spec_bytes`: empty
+    bytes = accept, non-empty bytes = a ``{"code", "field", "message"}``
+    reject verdict. A :class:`CowboyProtocolError` is raised only when
+    ``spec_json`` fails to even deserialize into a ``JobSpec``.
+    """
+    if not isinstance(spec_json, str):
+        raise TypeError(f"spec_json must be str, got {type(spec_json).__name__}")
+    return host().call("cpw_validate_job_spec_json", spec_json.encode("utf-8"))
+
+
+# ─── RAS + CBFS control-plane signing bytes (COW-2636 / COW-2649 completion) ──
+#
+# These surface the canonical SIGNING-BYTE contract `-codec`'s `ras` +
+# `cbfs_signing` modules own — the same big-endian, EIP-55-address,
+# `Encoder`-domain bytes the chain (node) and the cbfs control-plane verify. A
+# non-Rust signer (the python-sdk) MUST derive the bytes it signs from here, not
+# re-implement them: a byte-level fork is exactly the "two implementations that
+# must agree" split that caused the 2026-07-11 outage (COW-2608). Every byte
+# comes from the SAME wasm the native golden gate pins (byte-identity proven by
+# `tests/test_golden.py` against `crates/cowboy-protocol-codec/fixtures/ras/`).
+#
+# Each takes ONE canyon-JSON document — the serde shape of the `-codec` struct
+# named in the docstring, byte-for-byte the fixtures' `input` (fixed-width byte
+# fields are JSON arrays of `u8`; `Address` is the `0x…` string; `Option<T>` is
+# the value or `null`). See the crate-level ABI doc in
+# ``crates/cowboy-protocol-wasm-ffi/src/lib.rs`` for the verbatim contract.
+
+
+def _signing_json(value: str, param: str) -> bytes:
+    """Validate a signing-input JSON string and encode it UTF-8 for the ABI."""
+    if not isinstance(value, str):
+        raise TypeError(f"{param} must be str, got {type(value).__name__}")
+    return value.encode("utf-8")
+
+
+def owner_authorization_signing_bytes(authorization_json: str) -> bytes:
+    """Return ``ras_owner_authorization_signing_bytes()`` for a ``RasOwnerAuthorization``.
+
+    The CBFS-key authorization over one RAS owner operation (CIP-9 §12.2.1).
+    ``authorization_json`` is the ``RasOwnerAuthorization`` JSON shape:
+    ``{version: u8, owner_address: "0x…", delegated_pubkey: [32 u8],
+    volume_id: [32 u8] | null, operation: str, valid_from_epoch: u64,
+    valid_until_epoch: u64, nonce: [16 u8], payload_hash: [32 u8],
+    signature: [64 u8]}``.
+
+    ``operation`` must be a known RAS owner op — the codec fails closed
+    (raising :class:`CowboyProtocolError` ``"unknown RAS operation"``) on an
+    unrecognized operation, so the signing bytes can never be computed for an
+    off-registry op.
+    """
+    return host().call(
+        "cpw_ras_owner_authorization_signing_bytes",
+        _signing_json(authorization_json, "authorization_json"),
+    )
+
+
+def owner_delegation_signing_bytes(delegation_json: str) -> bytes:
+    """Return ``ras_owner_delegation_signing_bytes()`` for a ``RasOwnerDelegation``.
+
+    The epoch-scoped owner delegation for relayer-submitted RAS instructions.
+    ``delegation_json`` is the ``RasOwnerDelegation`` JSON shape:
+    ``{wallet_address: "0x…", delegated_pubkey: [32 u8], scopes: [str],
+    service_class: ServiceClass,
+    chain_id: u64, network: str, aud: str, valid_from_epoch: u64,
+    valid_until_epoch: u64, signature: [65 u8]}``.
+
+    ``ServiceClass`` is ``"MOUNT_CAPABLE_V1"``, ``"NON_MOUNT_SERVICE_V1"``,
+    ``{"VOLUME_BOUND_SERVICE_V1": {volume_id: [32 u8], workload_id: [32 u8]}}``,
+    ``{"WORKLOAD_MOUNT_V1": {volume_id: [32 u8], workload_id: [32 u8]}}`` or
+    ``{"SERVICE_RELEASE_V1": {volume_id: [32 u8]}}``.
+    """
+    return host().call(
+        "cpw_ras_owner_delegation_signing_bytes",
+        _signing_json(delegation_json, "delegation_json"),
+    )
+
+
+def relay_authorization_signing_bytes(authorization_json: str) -> bytes:
+    """Return ``ras_relay_authorization_signing_bytes()`` for a ``RasRelayAuthorization``.
+
+    The relay-identity (Ed25519) proof over relay registry metadata.
+    ``authorization_json`` is the ``RasRelayAuthorization`` JSON shape:
+    ``{version: u8, owner_address: "0x…", node_id: [32 u8], operation: str,
+    valid_from_epoch: u64, valid_until_epoch: u64, nonce: [16 u8],
+    payload_hash: [32 u8], signature: [64 u8]}``.
+
+    ``operation`` must be a known RAS relay op (same fail-closed registry gate
+    as :func:`owner_authorization_signing_bytes`).
+    """
+    return host().call(
+        "cpw_ras_relay_authorization_signing_bytes",
+        _signing_json(authorization_json, "authorization_json"),
+    )
+
+
+def delegation_cert_signing_bytes(cert_json: str) -> bytes:
+    """Return ``delegation_cert_signing_bytes()`` for a ``DelegationCert`` (CIP-9 §7).
+
+    The canonical bytes the wallet's secp256k1 key signs to establish a
+    delegation certificate (every field EXCEPT ``signature``).
+    ``cert_json`` is the ``DelegationCert`` JSON shape:
+    ``{wallet_address: "0x…", cbfs_public_key: [32 u8], scope: str,
+    service_class: ServiceClass,
+    chain_id: u64, network: str, aud: str, expires_at_ms: u64,
+    signature: [u8]}``.
+
+    ``ServiceClass`` is ``"MOUNT_CAPABLE_V1"``, ``"NON_MOUNT_SERVICE_V1"``,
+    ``{"VOLUME_BOUND_SERVICE_V1": {volume_id: [32 u8], workload_id: [32 u8]}}``,
+    ``{"WORKLOAD_MOUNT_V1": {volume_id: [32 u8], workload_id: [32 u8]}}`` or
+    ``{"SERVICE_RELEASE_V1": {volume_id: [32 u8]}}``.
+    """
+    return host().call(
+        "cpw_cbfs_delegation_cert_signing_bytes",
+        _signing_json(cert_json, "cert_json"),
+    )
+
+
+def delegation_cert_hash(cert_json: str) -> bytes:
+    """Return ``delegation_cert_hash()`` — the 32-byte keccak256 of
+    :func:`delegation_cert_signing_bytes`.
+
+    The digest the wallet's secp256k1 key actually signs (and which owner
+    cap-token verification recovers the wallet address from). ``cert_json`` is
+    the same ``DelegationCert`` JSON shape as
+    :func:`delegation_cert_signing_bytes`; returns 32 raw bytes.
+    """
+    return host().call(
+        "cpw_cbfs_delegation_cert_hash",
+        _signing_json(cert_json, "cert_json"),
+    )
+
+
+def owner_cap_token_signing_bytes(token_json: str) -> bytes:
+    """Return ``owner_cap_token_signing_bytes()`` for an ``OwnerCapTokenV1``.
+
+    The canonical bytes the cbfs Ed25519 key signs for an owner-issued
+    capability token (covers every field except ``owner_signature``; the
+    embedded delegation cert is included in its WIRE form, signature and all).
+    ``token_json`` is the ``OwnerCapTokenV1`` JSON shape:
+    ``{version: u8, volume_id: [32 u8], volume_name: str, owner_address: "0x…",
+    access_mode: "WriteOnly" | "ReadOnly" | "ReadWrite", path_prefix: str,
+    valid_from_ms: u64, valid_until_ms: u64, mount: bool, sync_interval: u32,
+    delegation_cert: {DelegationCert}, owner_signature: [u8]}`` — where
+    ``delegation_cert`` is the nested :func:`delegation_cert_signing_bytes`
+    shape.
+    """
+    return host().call(
+        "cpw_cbfs_owner_cap_token_signing_bytes",
+        _signing_json(token_json, "token_json"),
+    )
+
+
+def delegated_request_signing_bytes(request_input_json: str) -> bytes:
+    """Return ``delegated_request_signing_bytes()`` for a per-request signature.
+
+    The challenge-bound bytes the cbfs key signs so a captured token cannot be
+    replayed (method ‖ path ‖ ``keccak256(body)`` ‖ timestamp ‖ challenge).
+    ``request_input_json`` is the ``DelegatedRequestInput`` JSON shape:
+    ``{method: str, path_and_query: str, body: [u8], timestamp_ms: u64,
+    nonce_or_challenge: [16 u8]}`` (``body`` is the raw request body as a JSON
+    array of ``u8``; it is hashed, not embedded verbatim).
+    """
+    return host().call(
+        "cpw_cbfs_delegated_request_signing_bytes",
+        _signing_json(request_input_json, "request_input_json"),
+    )
+
+
+def relay_usage_signing_bytes(usage_input_json: str) -> bytes:
+    """Return ``relay_usage_signing_bytes()`` for a relay usage report.
+
+    The domain-separated bytes a relay's Ed25519 identity key signs for a
+    periodic registry usage report (covers every ``report`` field except its
+    own ``signature``). ``usage_input_json`` is the ``RelayUsageSigningInput``
+    JSON shape: ``{chain_id: u64, network: str, report: {ReportUsageRequest}}``
+    where ``report`` carries the full usage counters plus any
+    ``drain_absorption_receipts`` (each folded in whole, signature included).
+    """
+    return host().call(
+        "cpw_cbfs_relay_usage_signing_bytes",
+        _signing_json(usage_input_json, "usage_input_json"),
+    )

cowboy_protocol/_host.py

@@ -0,0 +1,204 @@
+"""Internal wasmtime host for the ``cowboy-protocol-wasm-ffi`` module.
+
+This module loads the bundled non-JS, flat-C-ABI ``.wasm`` (built from
+``crates/cowboy-protocol-wasm-ffi`` via ``build-ffi.sh``) with the
+``wasmtime`` pip package and drives its flat ABI:
+
+  * ``cpw_alloc(len) -> ptr``                            (host input buffers)
+  * ``cpw_free(ptr, len)``                               (free input + output)
+  * ``cpw_<fn>(in_ptr, in_len) -> u64``                  (packed ``(ptr<<32)|len``)
+  * ``cpw_last_error() -> u64``                          (packed error message)
+
+Every codec call returns a packed ``u64``: ``out_ptr = ret >> 32`` and
+``out_len = ret & 0xFFFF_FFFF``. ``out_ptr == 0`` is the error sentinel; on
+error we read ``cpw_last_error`` and raise :class:`CowboyProtocolError`.
+
+The module declares NO imports (no ``__wbindgen_*``, no ``getrandom/js``), so it
+instantiates with an empty import set. See the crate-level docs in
+``crates/cowboy-protocol-wasm-ffi/src/lib.rs`` for the verbatim ABI contract.
+
+This host is single-threaded by design (mirrors the wasm's single-instance,
+``thread_local`` last-error slot). A module-global lock serializes all calls so
+the alloc/call/read/free dance and the last-error read stay coherent even if a
+caller touches the API from multiple threads.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import threading
+
+from wasmtime import Engine, Instance, Module, Store
+
+#: Filename of the bundled wasm artifact (committed package data; kept in sync
+#: with a fresh ``build-ffi.sh`` build by the CI anti-drift gate).
+WASM_FILENAME = "cowboy_protocol_wasm_ffi.wasm"
+
+#: The flat-ABI codec exports, each ``(in_ptr: u32, in_len: u32) -> u64``: the
+#: eight transaction-codec exports, the five ``JobSpec`` bridges (COW-2440
+#: slice-4 Part A), and the eight RAS + CBFS control-plane signing/hash bridges
+#: (COW-2636/2649 completion WS-P1).
+_CODEC_FNS = (
+    "cpw_signing_preimage",
+    "cpw_signing_hash",
+    "cpw_signing_hash_hex",
+    "cpw_encode_transaction",
+    "cpw_encode_submission",
+    "cpw_sign",
+    "cpw_sign_transaction",
+    "cpw_address_from_private_key",
+    "cpw_normalize_job_request",
+    "cpw_encode_job_spec_json",
+    "cpw_decode_job_spec_to_json",
+    "cpw_validate_job_spec_bytes",
+    "cpw_validate_job_spec_json",
+    # RAS consensus-auth signing bytes (COW-2636).
+    "cpw_ras_owner_authorization_signing_bytes",
+    "cpw_ras_owner_delegation_signing_bytes",
+    "cpw_ras_relay_authorization_signing_bytes",
+    # CBFS control-plane signing bytes + the delegation-cert hash (COW-2649).
+    "cpw_cbfs_delegation_cert_signing_bytes",
+    "cpw_cbfs_delegation_cert_hash",
+    "cpw_cbfs_owner_cap_token_signing_bytes",
+    "cpw_cbfs_delegated_request_signing_bytes",
+    "cpw_cbfs_relay_usage_signing_bytes",
+)
+
+
+class CowboyProtocolError(Exception):
+    """Raised when a wasm codec call returns the error sentinel.
+
+    The message is the UTF-8 string retrieved from ``cpw_last_error`` (e.g.
+    ``"invalid transaction JSON: ..."`` or ``"invalid secp256k1 private
+    key: ..."``).
+    """
+
+
+def _wasm_bytes() -> bytes:
+    """Read the bundled ``.wasm`` from package data."""
+    # Chain single-arg joinpath calls: multi-arg Traversable.joinpath(*parts) is
+    # only guaranteed on 3.11+, but this package supports 3.10+ (a zip/namespace
+    # import on 3.10 would TypeError on the multi-arg form).
+    return (
+        importlib.resources.files(__package__)
+        .joinpath("_wasm")
+        .joinpath(WASM_FILENAME)
+        .read_bytes()
+    )
+
+
+class _Host:
+    """A loaded wasm instance plus typed handles to its flat ABI.
+
+    All public methods take/return raw ``bytes`` (or ``str`` for the error
+    path); the higher-level Pythonic API lives in :mod:`cowboy_protocol`.
+    """
+
+    def __init__(self) -> None:
+        engine = Engine()
+        module = Module(engine, _wasm_bytes())
+
+        # No-JS-imports invariant: a non-JS wasm host provides NO imports. The
+        # module must declare none (any __wbindgen_* / getrandom-js import would
+        # appear here and would make the empty-import instantiation below fail).
+        imports = list(module.imports)
+        if imports:
+            names = [f"{i.module}::{i.name}" for i in imports]
+            raise CowboyProtocolError(
+                "ffi wasm must have NO imports (no JS/wasm-bindgen host "
+                f"coupling); found: {names}"
+            )
+
+        self._store = Store(engine)
+        instance = Instance(self._store, module, [])
+        exports = instance.exports(self._store)
+
+        self._memory = exports["memory"]
+        self._alloc = exports["cpw_alloc"]
+        self._free = exports["cpw_free"]
+        self._last_error = exports["cpw_last_error"]
+        self._codec = {name: exports[name] for name in _CODEC_FNS}
+        self._lock = threading.Lock()
+
+    # ── linear-memory helpers ────────────────────────────────────────────────
+
+    def _read_mem(self, ptr: int, length: int) -> bytes:
+        """Copy ``[ptr, ptr+length)`` out of wasm linear memory."""
+        if length == 0:
+            return b""
+        data = self._memory.read(self._store, ptr, ptr + length)
+        return bytes(data)
+
+    def _write_input(self, data: bytes) -> int:
+        """Allocate a wasm buffer and copy ``data`` into it; return its ptr.
+
+        Returns 0 for empty input (matching ``cpw_alloc(0) == 0``); the codec
+        fns treat ``(0, 0)`` as an empty slice.
+        """
+        if not data:
+            return 0
+        ptr = self._alloc(self._store, len(data))
+        if ptr == 0:
+            raise CowboyProtocolError(
+                f"cpw_alloc returned null for a {len(data)}-byte input (OOM?)"
+            )
+        self._memory.write(self._store, data, ptr)
+        return ptr
+
+    def _take_last_error(self) -> str:
+        """Read + free the pending ``cpw_last_error`` message (or a fallback)."""
+        packed = self._last_error(self._store)
+        ptr = (packed >> 32) & 0xFFFF_FFFF
+        length = packed & 0xFFFF_FFFF
+        if ptr == 0:
+            return "<no error message>"
+        msg = self._read_mem(ptr, length)
+        self._free(self._store, ptr, length)
+        return msg.decode("utf-8", errors="replace")
+
+    # ── the alloc / write / call / read / free dance ─────────────────────────
+
+    def call(self, func: str, data: bytes) -> bytes:
+        """Invoke a codec export and return its raw output bytes.
+
+        Handles the full ABI dance: alloc + write the input, call, read the
+        packed return, copy the output out, and free BOTH buffers (in a
+        ``finally`` so they are reclaimed even if a step raises). On the error
+        sentinel (``out_ptr == 0``) reads ``cpw_last_error`` and raises
+        :class:`CowboyProtocolError`.
+        """
+        fn = self._codec[func]
+        with self._lock:
+            in_ptr = self._write_input(data)
+            in_len = len(data)
+            try:
+                packed = fn(self._store, in_ptr, in_len)
+            finally:
+                if in_ptr != 0:
+                    self._free(self._store, in_ptr, in_len)
+
+            out_ptr = (packed >> 32) & 0xFFFF_FFFF
+            out_len = packed & 0xFFFF_FFFF
+            if out_ptr == 0:
+                raise CowboyProtocolError(self._take_last_error())
+            try:
+                return self._read_mem(out_ptr, out_len)
+            finally:
+                self._free(self._store, out_ptr, out_len)
+
+
+# A single process-wide host instance, created lazily on first use. The wasm is
+# single-threaded and the host serializes calls under a lock, so one instance is
+# correct and avoids re-reading/compiling the module per call.
+_HOST: _Host | None = None
+_HOST_LOCK = threading.Lock()
+
+
+def host() -> _Host:
+    """Return the process-wide :class:`_Host`, instantiating it on first call."""
+    global _HOST
+    if _HOST is None:
+        with _HOST_LOCK:
+            if _HOST is None:
+                _HOST = _Host()
+    return _HOST