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 dispatches0x01and0x02Intent::PairandIntent::Sessionstreams 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 starveaccept_session(and vice versa), whileset_pair_enabled(false)disables and clears both v1 and v2 pair queues andclose()wakes waiting callers immediately. - Durable roster persistence: Host key rotations and rotation-fork revocations during
connect, as well as CRL updates (including session-terminating0x03 REVOCATIONframes), are persisted toStateStoreacrosstendril-ffi, Python, and Node. These nativeEndpointbindings assume single-process ownership of astate_dir(persisting atomic snapshots under.roster.lock), whereas multi-process CLI workflows (tendril servepaired with CLI subcommands) coordinate via transactionalStateStore::update_rosterupdates and liveRosterStampreloads.tendril-ffialso exposestendril_endpoint_new_from_stateandtendril_{endpoint_export_identity,endpoint_export_roster,session_export_roster}_jsonfor host keystores (Android/Apple) that store sealed state outsidestate_dir. - Full-duplex session concurrency:
tendril-runtimesplits streams intoPathReaderandPathWriter(PathStream::into_split) behindConcurrentSession(reader -> writer -> machine -> roster -> pending_eventslock ordering,shutdown()wakeup, and freshcurrent_unix_secsreads insidenext_event_now), so parkedpoll_event/PollEventcalls do not blocksend_data,rekey,authorize, orclose/ shutdown across FFI, Go, Python, and Node. - Go (
bindings/go): Linkslibtendril_ffithrough cgo againstcrates/tendril-ffi/include/tendril.h, rejecting embedded NUL bytes in string parameters. - Python (
bindings/python): Builds a PyO3abi3-py39extension module (tendril._tendril) withunsafe_code = "forbid", releasing the GIL viapy.detacharound Argon2 derivation (compute_code_mac) and everyEndpoint/Session(Arc<ConcurrentSession>) lock, disk I/O, or blocking runtime operation (info_jsonis a lock-free metadata serialization). - Node.js (
bindings/node): Builds anapi-rsN-API v8 native addon (index.node) withunsafe_code = "forbid", validating safe non-negative integers (0..=Number.MAX_SAFE_INTEGER) at the JS/N-API boundary and offloading Argon2 (computeCodeMac) and asyncEndpoint/ConcurrentSessionoperations 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 viatendril_last_error.
Language bindings summary
Go (bindings/go)
- Exposes size constants (
SigningPubLen = 1984,SigningHashLen = 32), typed wrappers (Endpoint,Session,EndpointInfoincludingSigningPubHashandRelayPub,PairInitiateResult,PairAcceptResult,EnrollInitiateResult,SessionEventincludingAudit,ErrWouldBlock),ServeDirect,ServeRelay,ServeP2p, M2M methods (AddTrustAnchortaking1984bytes,RevokeTrustAnchor,MintEnrollmentToken,EnrollInitiateaccepting1984-byte keys or32-byte SHA-256 hash pins), and pure helper functions (DeviceID,FingerprintHost,FingerprintDevice,PairingSAS,ComputeCodeMAC,VerifyRotationChainJSON,VerifyGrantJSON). - Guards
Endpointwithsync.RWMutex(soClose()signalstendril_endpoint_closewhile releasing in-flight calls before taking exclusiveLock()to free), guardsSessionwithsync.RWMutex+tendril_session_shutdown(allowing concurrent full-duplexSendData/Rekey/PollEvent/Close), validates strings against embedded NUL bytes, pairs pointer and byte-slice reads withruntime.KeepAlive, and pins OS threads viaruntime.LockOSThread()/runtime.UnlockOSThread()around cgo calls andtendril_last_error()reads undergo test -race.
Python (bindings/python)
- Exposes
Endpoint(withinfo_jsonreturningsigning_pub,signing_pub_hash, andrelay_pub;serve_direct,serve_relayusing the 32-byte Ed25519 relay prefix,serve_p2p,pair_initiate,connectdelegating dialing internally totendril-runtime::dial_endpointforiroh://,overlay://,broker+ws(s)://,ws(s)://, local, and direct targets, plus M2M methodsadd_trust_anchortaking1984bytes,revoke_trust_anchor,mint_enrollment_token, andenroll_initiateaccepting1984-byte keys or32-byte hash pins),Session,device_id,fingerprint_host,fingerprint_device,pairing_sas,compute_code_mac,verify_rotation_chain_json, andverify_grant_jsonfromtendril. compute_code_macand all blocking, mutex-acquiring, or disk-persistingEndpointandSessionmethods release the GIL viapy.detach, verified by a multi-threaded heartbeat test during concurrentcompute_code_macArgon2 execution, M2M replay/revocation tests, and concurrent handshake threads.
Node.js (bindings/node)
- Exposes
Endpoint(infoJsonreturningsigning_pub,signing_pub_hash, andrelay_pub),Session(non-constructible directly viaprivate constructor()inbindings/node/index.d.ts), synchronous hash/verifier helpers (deviceId,fingerprintHost,fingerprintDevice,pairingSas,verifyRotationChainJson,verifyGrantJson), synchronous M2M management methods (addTrustAnchortaking1984bytes,revokeTrustAnchor,mintEnrollmentToken), and asyncPromisemethods (computeCodeMac,serveDirect,serveRelay,serveP2p,pairInitiate,pairAccept,enrollInitiateaccepting1984-byte keys or32-byte hash pins,connect,acceptSession,sendData,pollEvent,authorize,rekey,close). - Verified by a
setIntervaltimer responsiveness test running alongside concurrentcomputeCodeMacArgon2 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 graphLinked from
- Add C ABI, Go, Python, and Node bindings with conformance suiteLogs“FFI ABI and cross-language bindings”
- Harden bindings, FFI concurrency, mobile storage, and web SDK (Audit Batch 2B)Logs“FFI ABI and cross-language bindings”