Bindings API

Source

The crate is the contract. This page reflects crates/sdk/chio-binding-helpers in the chio repository: src/canonical.rs, src/hashing.rs, src/signing.rs, src/receipt.rs, src/capability.rs, src/manifest.rs, and src/error.rs. The C ABI comes from crates/sdk/chio-bindings-ffi/src/lib.rs and its Cargo.toml. The conformance corpus is tests/bindings/vectors/.

Status: shipped. Both crates carry the workspace version, 0.1.0, and set publish = false, so an SDK reaches them through a path dependency inside the workspace rather than from a registry.

Synopsis

The crate root re-exports one module per concern. These snake_case names are the reference names; a binding renames them to its own convention.

Scope

chio-binding-helpers fixes the contract in Rust. The TypeScript, Python, and Go SDKs mirror the same API shape, the same input and output rules, and the same error codes. The contract covers canonical JSON, hashing, signing, and verification of protocol objects; transport, authentication, session state, and orchestration live in the language SDKs.

What the contract owns

• Canonical JSON helpers (RFC 8785).
• SHA-256 hashing helpers for both bytes and UTF-8 strings.
• Ed25519 signing and verification helpers.
• Receipt parsing and verification helpers.
• Capability parsing and verification helpers.
• Signed manifest parsing and verification helpers.
• Delegation-chain shape validity, returned as a field of capability verification and walked through chio-core.
• Stable, bindings-oriented error codes.

What the language SDKs own

• Session state machines.
• Remote HTTP or stream transports.
• Auth discovery, OAuth, token exchange, and token providers.
• Task orchestration and nested callback routers.
• Trust-control service clients.
• The kernel execution runtime.

Public functions

Canonical JSON

• canonicalize_json_str(input: &str) -> Result<String>

RFC 8785 JSON Canonicalization Scheme. The helper sorts object keys lexicographically by UTF-16 code unit, emits numbers in ECMAScript Number.prototype.toString form, and writes no insignificant whitespace. Two inputs that parse to the same JSON value produce the same output.

Hashing

• sha256_hex_bytes(input: &[u8]) -> String
• sha256_hex_utf8(input: &str) -> String

SHA-256 over the input, hex-encoded lowercase. sha256_hex_utf8 calls sha256_hex_bytes on the UTF-8 encoding of the string, with no byte-order mark.

Ed25519 signing

• is_valid_public_key_hex(value): parses as a Chio public key. Bare hex is read as Ed25519 (64 lowercase hex characters); a p256: or p384: prefix selects an ECDSA key, and a hybrid: prefix selects a hybrid classical and post-quantum key.
• is_valid_signature_hex(value): parses as a Chio signature. Bare hex is read as Ed25519 (128 lowercase hex characters); the same p256:, p384:, and hybrid: prefixes select the matching algorithm.
• public_key_hex_matches(left, right): case-insensitive equality after normalizing the hex. It is an ordinary string comparison, not a constant-time one.
• sign_utf8_message_ed25519(input, seed_hex) -> Utf8MessageSignature
• verify_utf8_message_ed25519(input, public_key_hex, signature_hex) -> bool
• sign_json_str_ed25519(input, seed_hex) -> CanonicalJsonSignature
• verify_json_str_signature_ed25519(input, public_key_hex, signature_hex) -> bool

The JSON helpers canonicalize the input before they sign or verify it, so an already-canonical JSON string and its non-canonical equivalent produce the same signature. CanonicalJsonSignature returns that canonical form alongside public_key_hex and signature_hex.

Receipts

• parse_receipt_json(input) -> ChioReceipt
• receipt_body_canonical_json(receipt) -> String
• verify_receipt(receipt) -> ReceiptVerification
• verify_receipt_json(input) -> ReceiptVerification
• verify_receipt_with_trusted_signers(receipt, trusted_signers) -> ReceiptVerification
• verify_receipt_with_trusted_signer_hex(receipt, trusted_signers) -> ReceiptVerification
• verify_receipt_json_with_trusted_signer_hex(input, trusted_signers) -> ReceiptVerification

A receipt verifies when its canonical-body signature checks against the embedded kernel_key and the parameter hash in the receipt equals SHA-256 of the canonical action arguments. Signature verification dispatches on the key and signature prefix, accepting Ed25519 (bare hex), p256:, p384:, and hybrid: material. verify_receipt calls verify_receipt_with_trusted_signers(receipt, &[]); the trusted-signer variants additionally require the receipt's kernel_key to appear in the supplied signer set.

ReceiptVerification carries signature_valid, parameter_hash_valid, receipt_id_valid, decision (a ReceiptDecisionKind of Allow, Deny, Cancelled, Incomplete, or None), receipt_kind, boundary_class, trust_level, result, authorized, signer_key_hex, signer_trusted, and ok. authorized is true only when the receipt is a mediated decision at the prevent boundary with an Allow decision and the signature, parameter-hash, receipt-id, and trusted-signer checks all pass. A valid trace or advisory receipt is evidence, and it does not authorize a call.

Capabilities

• parse_capability_json(input) -> CapabilityToken
• capability_body_canonical_json(capability) -> String
• verify_capability(capability, now_secs: u64, max_delegation_depth: Option<u32>) -> CapabilityVerification
• verify_capability_json(input, now_secs: u64, max_delegation_depth: Option<u32>) -> CapabilityVerification

verify_capability takes the parsed token, the current Unix timestamp in seconds, and an optional maximum delegation depth. The returned CapabilityVerification carries signature_valid, delegation_chain_shape_valid, time_valid, and a time_status of valid, not_yet_valid, or expired. The delegation-chain walk validates chain shape: each per-link signature, delegator-to-delegatee continuity, timestamp ordering, and chain length against max_delegation_depth. It does not compare parent and child scopes. Scope-attenuation and chain-binding enforcement is a stricter path in chio-core that this call does not invoke, which is why the field is named delegation_chain_shape_valid.

use std::time::{SystemTime, UNIX_EPOCH};

use chio_binding_helpers::{parse_capability_json, verify_capability};

let cap = parse_capability_json(&json)?;
let now = SystemTime::now().duration_since(UNIX_EPOCH)?.as_secs();
let max_delegation_depth = Some(8_u32);

let verification = verify_capability(&cap, now, max_delegation_depth)?;
assert!(verification.signature_valid);
assert!(verification.delegation_chain_shape_valid);
assert!(verification.time_valid);

Signed manifests

• parse_signed_manifest_json(input) -> SignedManifest
• signed_manifest_body_canonical_json(signed_manifest) -> String
• verify_signed_manifest(signed_manifest) -> ManifestVerification
• verify_signed_manifest_json(input) -> ManifestVerification

ManifestVerification carries structure_valid, signature_valid, embedded_public_key_valid, and embedded_public_key_matches_signer.

C ABI

crates/sdk/chio-bindings-ffi wraps the same helpers behind a C calling convention. Its Cargo.toml declares crate-type = ["staticlib", "cdylib", "rlib"], so the workspace build produces a static archive, a shared library, and a Rust library from one crate. A language without a Rust toolchain links the shared library and calls the symbols below.

Two #[repr(C)] structs carry every result. ChioFfiBuffer is a ptr and a len. ChioFfiResult is a status, an error_code, and a data buffer. Status is CHIO_FFI_STATUS_OK, CHIO_FFI_STATUS_ERROR, CHIO_FFI_STATUS_PANIC, or CHIO_FFI_STATUS_NULL_ARGUMENT, and error_code is the numeric form of the error code table below. The caller frees every returned buffer with chio_buffer_free.

The table holds 14 exported symbols, every #[no_mangle] pub extern "C" item in crates/sdk/chio-bindings-ffi/src/lib.rs. Pointer arguments are C strings unless a length parameter follows, and a null pointer returns CHIO_FFI_STATUS_NULL_ARGUMENT rather than dereferencing it.

Input and output rules

Prefer:

• JSON-string input for structured payloads.
• UTF-8 string input for signed text helpers.
• Byte-slice input when byte identity matters.
• Verification result structs, so a caller reads which check failed.

Avoid:

• Exposing deep internal Rust types across the binding boundary.
• Opaque handles unless they wrap reusable compiled objects.
• Async APIs in the invariants layer.
• Ownership-sensitive runtime state.

Error codes

ErrorCode in src/error.rs enumerates the codes, and Error::code maps every error the crate raises onto one of them. The enum carries serde(rename_all = "snake_case"), so the serialized value is the code below. An SDK exposes it through a typed error class. Depend on the code, not on the Rust enum spelling or any message text. Removing or renaming a code breaks that dependency.

Cross-language conformance

The corpus lives at tests/bindings/vectors/, one directory per family, each with a v1.json of inputs and expected outputs. MANIFEST.sha256 pins the bytes of every vector file, so a binding compares against the same corpus the Rust reference does.

Each language runs the corpus through its own test command.

$ cargo test -p chio-conformance              # Rust reference
$ cd sdks/typescript/chio-ts && npm test      # TypeScript
$ cd sdks/python/chio-py && pytest            # Python
$ cd sdks/go/chio-go && go test ./...         # Go

Change rules

The crate doc comment fixes the boundary: session runtime, transport, auth, and callback orchestration stay in the language-native SDKs. Three rules follow from it.

• A new public entrypoint carries an owning use case, a unit test, or both.
• A change that widens scope into transport or runtime behavior is rejected by default.
• An SDK consumes helpers through this facade rather than reaching into chio-core or chio-manifest directly. The two dependencies are declared in Cargo.toml so the facade can reach them; a binding reads the facade.

Versioning

Both crates take their version from the workspace manifest, currently 0.1.0, and both set publish = false. The C ABI carries a second number: CHIO_FFI_ABI_VERSION, returned by chio_ffi_abi_version and repeated in the chio_ffi_build_info JSON, which a caller reads to confirm the struct layout it compiled against.

Related

• TypeScript SDK (@chio-protocol/sdk): the transport, session, and auth layers over this contract.
• Python SDK (chio-sdk, imported as chio)
• Go SDK (github.com/backbay-labs/chio/sdks/go/chio-go)
• Rust SDK: the same crate as a dependency, with the guard SDK beside it.
• Receipt Format: the field semantics the receipt helpers verify.