FFI ABI and cross-language bindings

Callback-free C ABI surface, thin Go/Python/Node bindings, and Gate

Tendril keeps one Rust core (tendril-core + tendril-runtime) across every target language. Host-language bindings delegate wire framing, Noise handshakes, pairing codes, roster persistence, rotation verification, and default-deny capability checks directly to Rust rather than duplicating protocol logic.

Core architecture

Host app (Go / Python / Node.js)
  -> Thin language wrapper (mutex / GIL release / N-API Promise)
    -> C ABI (`tendril-ffi`) or direct Rust bridge (PyO3 / napi-rs)
      -> `tendril-runtime` (`InboundRouter`, `StateStore`, `SessionDriver`) + `tendril-core`
  • Shared inbound routing (InboundRouter): Peeks each incoming stream's cleartext preamble under the pre-auth rate limiter and dispatches 0x01 and 0x02 Intent::Pair and Intent::Session streams onto protocol-isolated bounded queues (InboundQueues for v1/v2 pairing and sessions) with isolated half-open budgets, rate limiters, and automatic expiration (DEFAULT_PRE_AUTH_TIMEOUT), so unconsumed pairing floods never block or starve accept_session (and vice versa), while set_pair_enabled(false) disables and clears both v1 and v2 pair queues and close() wakes waiting callers immediately.
  • Durable roster persistence: Host key rotations and rotation-fork revocations during connect, as well as CRL updates (including session-terminating 0x03 REVOCATION frames), are persisted to StateStore across tendril-ffi, Python, and Node. These native Endpoint bindings assume single-process ownership of a state_dir (persisting atomic snapshots under .roster.lock), whereas multi-process CLI workflows (tendril serve paired with CLI subcommands) coordinate via transactional StateStore::update_roster updates and live RosterStamp reloads. tendril-ffi also exposes tendril_endpoint_new_from_state and tendril_{endpoint_export_identity,endpoint_export_roster,session_export_roster}_json for host keystores (Android/Apple) that store sealed state outside state_dir.
  • Full-duplex session concurrency: tendril-runtime splits streams into PathReader and PathWriter (PathStream::into_split) behind ConcurrentSession (reader -> writer -> machine -> roster -> pending_events lock ordering, shutdown() wakeup, and fresh current_unix_secs reads inside next_event_now), so parked poll_event / PollEvent calls do not block send_data, rekey, authorize, or close / shutdown across FFI, Go, Python, and Node.
  • Go (bindings/go): Links libtendril_ffi through cgo against crates/tendril-ffi/include/tendril.h, rejecting embedded NUL bytes in string parameters.
  • Python (bindings/python): Builds a PyO3 abi3-py39 extension module (tendril._tendril) with unsafe_code = "forbid", releasing the GIL via py.detach around Argon2 derivation (compute_code_mac) and every Endpoint/Session (Arc<ConcurrentSession>) lock, disk I/O, or blocking runtime operation (info_json is a lock-free metadata serialization).
  • Node.js (bindings/node): Builds a napi-rs N-API v8 native addon (index.node) with unsafe_code = "forbid", validating safe non-negative integers (0..=Number.MAX_SAFE_INTEGER) at the JS/N-API boundary and offloading Argon2 (computeCodeMac) and async Endpoint/ConcurrentSession operations onto Tokio so the JS event loop stays responsive.

C ABI surface (crates/tendril-ffi)

crates/tendril-ffi/include/tendril.h is manually maintained in lockstep with crates/tendril-ffi/src/lib.rs, exports key-length constants (TENDRIL_KEY_LEN = 32, TENDRIL_SIGNING_PUB_LEN = 1984, TENDRIL_SIGNING_HASH_LEN = 32), and defines a callback-free polled C ABI backed by a multi-threaded Tokio runtime:

Symbol Group Representative Functions Ownership & Error Contract
Status & cleanup tendril_last_error, tendril_string_free Negative TendrilResult populates UTF-8 char-boundary truncated thread-local error buffer; heap strings returned via char ** are zeroized and released with tendril_string_free
Vector & core helpers tendril_device_id, tendril_fingerprint_host, tendril_fingerprint_device, tendril_pairing_sas, tendril_compute_code_mac, tendril_verify_rotation_chain_json, tendril_verify_grant_json Pure delegation to tendril-core with early out-pointer validation and catch_unwind panic boundaries
Endpoint lifecycle tendril_endpoint_new, tendril_endpoint_new_from_state, tendril_endpoint_close, tendril_endpoint_free, tendril_endpoint_info_json, tendril_endpoint_export_identity_json, tendril_endpoint_export_roster_json, tendril_endpoint_configure_transports_json, tendril_endpoint_mint_relay_ticket, tendril_endpoint_serve_direct, tendril_endpoint_serve_relay, tendril_endpoint_serve_relay_v2, tendril_endpoint_serve_p2p, tendril_endpoint_issue_code, tendril_endpoint_pair_initiate, tendril_endpoint_pair_v2_initiate, tendril_endpoint_pair_accept, tendril_endpoint_pair_v2_accept, tendril_endpoint_confirm_peer, tendril_endpoint_mint_grant, tendril_endpoint_revoke_peer, tendril_endpoint_add_trust_anchor, tendril_endpoint_revoke_trust_anchor, tendril_endpoint_mint_enrollment_token, tendril_endpoint_enroll_initiate Opaque TendrilEndpoint *; NULL or empty state_dir selects ephemeral in-memory operation unless tendril_endpoint_new_from_state supplies in-memory identity/roster JSON; tendril_endpoint_configure_transports_json configures managed relay admission, P2P relay pools/tokens, and wake providers via TransportConfigInput (#[serde(deny_unknown_fields)], ZeroizeOnDrop) accepting keys: relay_auth_secret, relay_ticket, p2p_relay_mode, p2p_relay_urls, p2p_pkarr, p2p_advertise_direct_addrs, p2p_allow_private_addrs, p2p_relay_auth_token, p2p_api_secret, wake_url, wake_adapter, wake_secret_b64, wake_auth_token, wake_pre_wake, wake_retry_delay_ms, wake_max_attempts, and wake_timeout_ms; tendril_endpoint_mint_relay_ticket signs Tier 3 RelayTicket JSON; tendril_endpoint_serve_relay_v2 binds a /v2/relay listener; tendril_endpoint_close wakes parked accepts before tendril_endpoint_free; manual tendril_endpoint_pair_initiate / tendril_endpoint_pair_v2_initiate (PAKE 0x02) record hosts in pending state requiring tendril_endpoint_confirm_peer before connect; tendril_endpoint_pair_v2_accept accepts inbound 0x02 PAKE pairing; tendril_endpoint_add_trust_anchor and tendril_endpoint_mint_enrollment_token enable opt-in M2M enrollment acceptance with atomic nonce burning prior to response transmission; tendril_endpoint_serve_p2p binds a deterministic HKDF-derived iroh listener ("default", "disabled"/"local", or relay URL) when compiled with p2p-iroh
Session lifecycle & polling tendril_session_connect, tendril_session_connect_v2, tendril_session_accept, tendril_session_accept_v2, tendril_session_shutdown, tendril_session_free, tendril_session_export_roster_json, tendril_session_send_data, tendril_session_poll_event, tendril_session_authorize, tendril_session_rekey, tendril_session_close Opaque TendrilSession * remains valid after tendril_endpoint_free and supports concurrent send/authorize/poll/shutdown; tendril_session_connect_v2 and tendril_session_accept_v2 drive Wire 0x02 pseudonymous sessions with padded/jittered transport; tendril_session_send_data checks len <= MAX_APP_DATA_LEN before reading caller buffers; tendril_session_poll_event validates out_event_json before polling and returns TENDRIL_OK (0), TENDRIL_WOULD_BLOCK (1), or TENDRIL_EOF (2)

TendrilResult status codes

  • TENDRIL_OK (0): operation succeeded.
  • TENDRIL_WOULD_BLOCK (1): timed poll completed with no queued event ready.
  • TENDRIL_EOF (2): peer stream ended cleanly.
  • Negative codes (TENDRIL_ERR_INVALID_ARG -1, TENDRIL_ERR_NOT_FOUND -2, TENDRIL_ERR_CLOSED -5, TENDRIL_ERR_PROTOCOL -6, TENDRIL_ERR_INTERNAL -7): error details are readable via tendril_last_error.

Language bindings summary

Go (bindings/go)

  • Exposes size constants (SigningPubLen = 1984, SigningHashLen = 32), typed wrappers (Endpoint, Session, EndpointInfo including SigningPubHash and RelayPub, PairInitiateResult, PairAcceptResult, EnrollInitiateResult, SessionEvent including Audit, ErrWouldBlock), ServeDirect, ServeRelay, ServeP2p, M2M methods (AddTrustAnchor taking 1984 bytes, RevokeTrustAnchor, MintEnrollmentToken, EnrollInitiate accepting 1984-byte keys or 32-byte SHA-256 hash pins), and pure helper functions (DeviceID, FingerprintHost, FingerprintDevice, PairingSAS, ComputeCodeMAC, VerifyRotationChainJSON, VerifyGrantJSON).
  • Guards Endpoint with sync.RWMutex (so Close() signals tendril_endpoint_close while releasing in-flight calls before taking exclusive Lock() to free), guards Session with sync.RWMutex + tendril_session_shutdown (allowing concurrent full-duplex SendData/Rekey/PollEvent/Close), validates strings against embedded NUL bytes, pairs pointer and byte-slice reads with runtime.KeepAlive, and pins OS threads via runtime.LockOSThread() / runtime.UnlockOSThread() around cgo calls and tendril_last_error() reads under go test -race.

Python (bindings/python)

  • Exposes Endpoint (with info_json returning signing_pub, signing_pub_hash, and relay_pub; serve_direct, serve_relay using the 32-byte Ed25519 relay prefix, serve_p2p, pair_initiate, connect delegating dialing internally to tendril-runtime::dial_endpoint for iroh://, overlay://, broker+ws(s)://, ws(s)://, local, and direct targets, plus M2M methods add_trust_anchor taking 1984 bytes, revoke_trust_anchor, mint_enrollment_token, and enroll_initiate accepting 1984-byte keys or 32-byte hash pins), Session, device_id, fingerprint_host, fingerprint_device, pairing_sas, compute_code_mac, verify_rotation_chain_json, and verify_grant_json from tendril.
  • compute_code_mac and all blocking, mutex-acquiring, or disk-persisting Endpoint and Session methods release the GIL via py.detach, verified by a multi-threaded heartbeat test during concurrent compute_code_mac Argon2 execution, M2M replay/revocation tests, and concurrent handshake threads.

Node.js (bindings/node)

  • Exposes Endpoint (infoJson returning signing_pub, signing_pub_hash, and relay_pub), Session (non-constructible directly via private constructor() in bindings/node/index.d.ts), synchronous hash/verifier helpers (deviceId, fingerprintHost, fingerprintDevice, pairingSas, verifyRotationChainJson, verifyGrantJson), synchronous M2M management methods (addTrustAnchor taking 1984 bytes, revokeTrustAnchor, mintEnrollmentToken), and async Promise methods (computeCodeMac, serveDirect, serveRelay, serveP2p, pairInitiate, pairAccept, enrollInitiate accepting 1984-byte keys or 32-byte hash pins, connect, acceptSession, sendData, pollEvent, authorize, rekey, close).
  • Verified by a setInterval timer responsiveness test running alongside concurrent computeCodeMac Argon2 promises, local P2P (serveP2p("disabled")) loopback tests, and M2M enrollment/replay/revocation conformance tests.

Full M2M enrollment parity (addTrustAnchor, revokeTrustAnchor, mintEnrollmentToken, and enroll / enrollInitiate) also extends across browser WebAssembly, Android Kotlin JNI, and Apple Swift; see Web and mobile bindings.

Gate #7 baselines (Linux x86_64 release)

Measured against stripped release builds (lto = "thin", codegen-units = 1, strip = true):

Binding / Crate Stripped Release Size Per-Call FFI Overhead (device_id) Measurement Method
tendril-ffi (--no-default-features, hybrid PQ) 4,834,416 bytes (4.61 MiB) Core-only Wave 2 PQ baseline stat -c%s on libtendril_ffi.so built with --no-default-features
tendril-ffi (default p2p-iroh, hybrid PQ) 15,196,176 bytes (14.49 MiB) Included via Go cgo baseline stat -c%s on target/release/libtendril_ffi.so
Go (bindings/go) Links libtendril_ffi.so 363.1 ns/op (2,924,054 iterations in 1s) Phase 3 go test -run=^$ -bench=BenchmarkFFIOverhead -benchtime=1s (runtime.LockOSThread)
Python (bindings/python, lib_tendril.so, p2p-iroh) 16,270,208 bytes (15.52 MiB, Phase 3 pre-PQ) 255.2 ns/op (100,000 calls in 0.0255s) Phase 3 stat -c%s on release .so; Phase 3 timeit calling tendril.device_id(k)
Node.js (bindings/node, libtendril_node.so, p2p-iroh) 16,441,984 bytes (15.68 MiB, Phase 3 pre-PQ) 475.6 ns/op (100,000 calls in 47.56ms) Phase 3 stat -c%s on release .node; Phase 3 performance.now() calling deviceId(k)

For mobile (aarch64-linux-android, Swift) and browser WASM bundle budgets and Argon2id timings, see Web and mobile bindings.

Verification

Each binding verifies the helper-level spec/vectors/ files (fingerprints.json, pairing_mac.json, rotation.json, and grants.json) offline (while spec/vectors/handshake.json and spec/vectors/m2m_enrollment.json are verified in Rust and Go via make vectors/check) and runs bidirectional client/host live interop against tendril-conformance-peer (covering pairing, SAS confirmation, M2M enrollment/replay/anchor-revocation, capability minting, encrypted data exchange, authorization, revocation, plus rekey in Python/Node bidirectional runs and Go concurrency tests):

make bindings/go      # build tendril-ffi and run Go cgo tests with -race
make bindings/python  # build _tendril.so and run Python unittest suite
make bindings/node    # build index.node and run node --test suite
make bindings/check   # run Go, Python, Node, Web WASM, and Kotlin JNI suites
make check            # run full workspace lint, Rust tests, vectors, and bindings

Connections

Local graph

Linked from